1 Copyright 2012 Oracle andor its affiliates All

1 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX-RS 2. 0: New and Noteworthy in the RESTful Web Services API John Clingan Java EE and Glass. Fish Product Manager john. clingan@oracle. com 2 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

What’s New in JAX-RS 2. 0 § JAX-RS Review § Client API § Common Configuration § Asynchronous Processing § Filters/Interceptors § Hypermedia Support § Server-side Content Negotiation 3 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 16 13

JAX-RS – Java API for RESTful Services Standard annotation-driven API that aims to help developers build RESTful Web services and clients in Java § POJO-Based Resource Classes § HTTP Centric Programming Model § Entity Format Independence § Container Independence § Included in Java EE 4 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX-RS Example. . . @POST @Path("/withdrawal") @Consumes("text/plain") @Produces("application/json") public Money withdraw( @Path. Param("card") String card, @Query. Param("pin") String pin, String amount) { return get. Money(card, pin, amount); } } 5 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX-RS Annotations 6 Method Annotation GET @GET Read, possibly cached POST @POST Update or create without a known ID PUT @PUT Update or create with a known ID DELETE @DELETE Remove HEAD @HEAD GET with no response OPTIONS @Options Supported methods Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX-RS Annotations (Continued) 7 Method Annotation @Path. Param Binds the value from URI, e. g. @Path. Param(“id”) @Query. Param Binds the value of query name/value, e. g. @Query. Param(“name”) @Cookie. Param Binds the value of a cookie, e. g. @Cookie. Param(“JSESSIONID”) @Header. Param Binds the value of a HTTP header, e. g. @Header. Param(“Accept”) @Form. Param Binds the value of an HTML form, e. g. @Form. Param(“name”) @Matrix. Param Binds the value of a matrix parameter, e. g. @Matrix. Param(“name”) Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Client API 8 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API Motivation § HTTP client libraries too low level § Leveraging providers/concepts from JAX-RS 1. x API § Proprietary APIs introduced by major implementations 9 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API // Get instance of Client client = Client. Builder. new. Client(); // Get account balance String bal = client. target("http: //. . . /atm/{card. Id}/balance"). resolve. Template("card. Id", "111122223333"). query. Param("pin", "9876"). request("text/plain"). get(String. class); 10 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API // Withdraw some money Money money = client. target("http: //. . . /atm/{card. Id}/withdrawal"). resolve. Template("card. Id", "111122223333"). query. Param("pin", "9876"). request("application/json"). post(text("50. 0"), Money. class); 11 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API Invocation invocation 1 = client. target("http: //. . . /atm/{card. Id}/balance")…. request(“text/plain”). build. Get(); Invocation invocation 2 = client. target("http: //. . . /atm/{card. Id}/withdraw")…. request("application/json"). build. Post(text("50. 0")); 12 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API Collection<Invocation> invocations = Arrays. as. List(inv 1, inv 2); Collection<Response> responses = Collections. transform( invocations, new F<Invocation, Response>() { public Response apply(Invocation invocation) { return invocation. invoke(); } }); 13 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Client API // Create client and register My. Provider 1 Client client = Client. Builder. new. Client(); client. register(My. Provider 1. class); // Create atm target; inherits My. Provider 1 Web. Target atm = client. target("http: //. . . /atm"); // Register My. Provider 2 atm. register(My. Provider 2. class); // Create balance target; inherits My. Provider 1, My. Provider 2 Web. Target balance = atm. path(”{card. Id}/balance"); // Register My. Provider 3 balance. register(My. Provider 3. class); 14 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Common Configuration 15 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration - Motivation Client-side client. register(Json. Message. Body. Reader. class). register(Json. Message. Body. Writer. class). register(Jsonp. Interceptor. class). property(“jsonp. callback. name”, “callback”). property(“jsonp. callback. query. Param”, “true”). . . 16 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration - Motivation Server-side public class My. App extends javax. ws. rs. core. Application { public Set<Class<? >> get. Classes() { Set<Class<? >> classes = new Hash. Set<…>(); . . . classes. add(Json. Message. Body. Reader. class); classes. add(Json. Message. Body. Writer. class); classes. add(Jsonp. Interceptor. class); . . . return classes; } } 17 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration - Solution Client-side client. register(Json. Message. Body. Reader. class). register(Json. Message. Body. Writer. class). register(Jsonp. Interceptor. class). property(“jsonp. callback. name”, “callback”). property(“jsonp. callback. query. Param”, “true”). . . Json. Feature jf = new Json. Feature(). enable. Callback. Query. Param(); client. register(jf); 18 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration - Solution Server-side public Set<Class<? >> get. Classes() {. . . classes. add(Json. Message. Body. Reader. class); classes. add(Json. Message. Body. Writer. class); classes. add(Jsonp. Interceptor. class); . . . } public Set<Class<? >> get. Classes() {. . . classes. add(Json. Feature. class); . . . } 19 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration public interface Configurable { Configuration get. Configuration(); Configurable property(String name, Object value); Configurable register(. . . ); } public interface Configuration { Set<Class> get. Classes(); Map<Class, Integer> get. Contracts(Class component. Class); Set<Object> get. Instances(); Map<String, Object> get. Properties(); Object get. Property(String name); Collection<String> get. Property. Names(); } 20 boolean is. Enabled(Feature feature); boolean is. Registered(Object component); . . . Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Common Configuration public interface Feature { boolean configure(Feature. Context context); } 21 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

A Feature Example public void Json. Feature implements Feature { public boolean configure(Feature. Context context) { context. register(Json. Message. Body. Reader. class). register(Json. Message. Body. Writer. class). register(Jsonp. Interceptor. class). property(CALLBACK_NAME, calback. Name). property(USE_QUERY_PARAM, use. Query. Param); return true; } } 22 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Dynamic Feature Server-side only public interface Dynamic. Feature { void configure(Resource. Info ri, Feature. Context context); } public interface Resource. Info { Method get. Resource. Method(); Class<? > get. Resource. Class(); } 23 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Asynchronous Processing 24 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing § Server API – Off-load I/O container threads – Efficient asynchronous event processing – Leverage Servlet 3. x async support (if available) § Client API – Asynchronous request invocation API 25 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing @Stateless @Path("/async/long. Running") public class My. Resource { @GET @Asynchronous public void long. Running. Op(@Suspended Async. Response ar) { ar. set. Timeout. Handler(new My. Timout. Handler()); ar. set. Timeout(15, SECONDS); final String result = execute. Long. Running. Operation(); } 26 } ar. resume(result); Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing: Server Side public interface Async. Response { public void resume(Object/Throwable response); public void cancel(int/Date retry. After); public boolean is. Suspended(); public boolean is. Cancelled(); public boolean is. Done(); public void set. Timeout(long time, Time. Unit unit); public void set. Timeout. Handler(Timeout. Handler handler); } 27 public Collection<Class<? >> register(Class<? > callback); public Map<Class<? >, Collection<Class<? >>> register(Class<? > callback, Class<? >. . . callbacks); public Collection<Class<? >> register(Object callback); public Map<Class<? >, Collection<Class<? >>> register(Object callback, Object. . . callbacks); Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing: Server Side @Target({Element. Type. PARAMETER}) @Retention(Retention. Policy. RUNTIME) @Documented public @interface Suspended { } public interface Timeout. Handler { void handle. Timeout(Async. Response async. Response); } 28 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing: Server Side public interface Completion. Callback { public void on. Complete(Throwable throwable); } public interface Connection. Callback { public void on. Disconnect(Async. Response disconnected); } 29 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Asynchronous Processing: Client Side Web. Target target = client. target("http: //. . . /balance”)… // Start async call and register callback Future<? > handle = target. request(). async(). get( new Invocation. Callback<String>() { void complete(String balance) { … } void failed(Invocation. Exception e) { … } }); // After waiting for too long… if (!handle. is. Done()) handle. cancel(true); 30 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Filters/Interceptors 31 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Filters & Interceptors Motivation § Customize JAX-RS request/response processing – Use Cases: Logging, Compression, Security, etc. § Introduced for client and server APIs § Replace existing proprietary support 32 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Filters & Interceptors Filter each incoming/outgoing message § Non-wrapping filter chain – Filters do not invoke next filter in the chain directly – Managed by the JAX-RS runtime § Each filter decides to proceed or break the chain 33 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. § Request – Container. Request. Filter, Client. Request. Filter § Response – Container. Response. Filter, Client. Response. Filter § Server-side specialties – @Pre. Matching, Dynamic. Feature Insert Information Protection Policy Classification from Slide 13

Filters & Interceptors A Logging Filter Exampe public class Request. Logging. Filter implements Container. Request. Filter { @Override public void filter(Container. Request. Context request. Context) { log(request. Context); } } 34 // non-wrapping => returns without invoking the next filter . . . Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Filters & Interceptors Intercept entity providers § Invoked ONLY when/if entity § Message. Body. Reader interceptor processing occurs – Reader. Interceptor interface – Performance boost § Message. Body. Writer interceptor § Wrapping interceptors chain – Each interceptor invokes the next one in the chain via context. proceed() 35 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 – Writer. Interceptor interface

Filters & Interceptors A Gzip Reader Interceptor Example public class Gzip. Interceptor implements Reader. Interceptor { @Override Object around. Read. From(Reader. Interceptor. Context ctx) { Input. Stream old = ctx. get. Input. Stream(); ctx. set. Input. Stream(new GZIPInput. Stream(old)); // wrapping => invokes the next interceptor Object entity = ctx. proceed(); } 36 } ctx. set. Input. Stream(old); return entity; Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Filters & Interceptors write(…) Writer Interceptor Request Filter Application Response Filter … … … Writer Interceptor Filter Transport Filter read(…) - optional MBR 37 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Reader Interceptor … MBW Reader Interceptor Insert Information Protection Policy Classification from Slide 13 Network

Filters & Interceptors read(…) - optional Reader Interceptor … Reader Interceptor MBR @Pre. Matching Request Filter Resource Matching Filter Network Response … Filter write(…) MBW 38 Writer Interceptor Copyright © 2012, Oracle and/or its affiliates. All rights reserved. … Writer Interceptor Insert Information Protection Policy Classification from Slide 13 Filter … Filter Request Application Filter Response

Bindings & Priorities § Binding Associating filters and interceptors with resource methods – Server-side concept – § Priority Declaring relative position in the execution chain – @Priority(int priority) – § Shared concept by filters and interceptors Scoped Binding 39 Static @Name. Binding Dynamic. Feature Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 Global Binding Default @Pre. Matching N/A

Bindings @Name. Binding @Target({Element. Type. TYPE, Element. Type. METHOD}) @Retention(value = Retention. Policy. RUNTIME) public @interface Logged {} @Provider @Logged @Priority(USER) public class Logging. Filter implements Container. Request. Filter, Container. Response. Filter { … } 40 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Bindings @Path("/greet/{name}") @Produces("text/plain") public class My. Resource. Class { @Logged @GET public String hello(@Path. Param("name") String name) { return "Hello " + name; } } 41 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

A Dynamic. Feature Example Server-side only public void Security. Feature implements Dynamic. Feature { public boolean configure(Resource. Info ri, Feature. Context context) { String[] roles = get. Roles. Allowed(ri); if (roles != null) { context. register(new Roles. Allowed. Filter(roles)); } }. . . } 42 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Hypermedia Support 43 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Hypermedia Support § REST Principles – Identifiers and Links – HATEOAS (Hypermedia As The Engine Of App State) § Link types: – Structural Links – Transitional Links 44 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Hypermedia Support Transitional Links Link: <http: //. . . /orders/1/ship>; rel=ship, <http: //. . . /orders/1/cancel>; rel=cancel. . . <order id="1"> <customer>http: //. . . /customers/11</customer> <address>http: //. . . /customers/11/address/1</address> <items> Structural <item> Links <product>http: //. . . /products/111</product> <quantity>2</quantity> </item> <items>. . . </order> 45 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Hypermedia § Link and Link. Builder classes – RFC 5988: Web Linking § Support for Link in Response. Builder and filters – Transitional links (headers) § Support for manual structural links – Via Link. Jaxb. Adapter & Link. Jaxb. Link § Create a resource target from a Link in Client API 46 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Hypermedia // Producer API (server-side) Link self = Link. from. Method(My. Resource. class, ”handle. Get”). build(); Link update = Link. from. Method(My. Resource. class, “handle. Post”). rel(”update”). build(); . . . Response res = Response. ok(order). link("http: //. . . /orders/1/ship", "ship"). links(self, update). build(); 47 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Hypermedia Response order = client. target(…). request("application/xml"). get(); // Consumer API (client-side) Link shipment. Link = order. get. Link(“ship”); if (shipment. Link != null) { Response shipment = client. target(shipment. Link). post(null); … } 48 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX RS 2. 0 Server-side Content Negotiation 49 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Server-side Content Negotiation GET http: //. . . /widgets 2 Accept: text/*; q=1 … Path("widgets 2") public class Widgets. Resource 2 { @GET @Produces("text/plain", "text/html") public Widgets get. Widget() {. . . } } 50 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Server Side Content Negotiation GET http: //. . . /widgets 2 Accept: text/*; q=1 … Path("widgets 2") public class Widgets. Resource 2 { @GET @Produces("text/plain; qs=0. 5", "text/html; qs=0. 75") public Widgets get. Widget() {. . . } } 51 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

JAX-RS 2. 0 Summary § Major New Features – Client API, Filters & Interceptors, Asynchronous Resources, Hypermedia § Many minor API improvements and extensions – Bean Validation, Request / Response, URI Builder, String Converters, @Bean. Param, Multivalued. Hash. Map, Generic. Type, … § DI Integration, , Java EE Security, MVC, high-level client API deferred 52 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

Additional Resources § Read JSR 343 specification at http: //jcp. org § Glass. Fish 4. 0 – http: //glassfish. java. net/ – http: //dlc. sun. com. edgesuite. net/glassfish/4. 0/promoted/ § Open Message Queue 5. 0 – http: //mq. java. net/5. 0. html 53 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13

54 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13