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

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

3. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 3 Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 16 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

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

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

6. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 6 JAX-RS Annotations MethodAnnotation GET@GETRead, possibly cached POST@POSTUpdate or create without a known ID PUT@PUTUpdate or create with a known ID DELETE@DELETERemove HEAD@HEADGET with no response OPTIONS@OptionsSupported methods

7. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 7 JAX-RS Annotations (Continued) MethodAnnotation @PathParamBinds the value from URI, e.g. @PathParam(“id”) @QueryParamBinds the value of query name/value, e.g. @QueryParam(“name”) @CookieParamBinds the value of a cookie, e.g. @CookieParam(“JSESSIONID”) @HeaderParamBinds the value of a HTTP header, e.g. @HeaderParam(“Accept”) @FormParamBinds the value of an HTML form, e.g. @FormParam(“name”) @MatrixParamBinds the value of a matrix parameter, e.g. @MatrixParam(“name”)

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

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

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

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

12. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 12 Client API Invocation invocation1 = client.target("http://.../atm/{cardId}/balance")….request(“text/plain”).buildGet(); Invocation invocation2 = client.target("http://.../atm/{cardId}/withdraw")….request("application/json").buildPost(text("50.0"));

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

14. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 14 Client API // Create client and register MyProvider1 Client client = ClientBuilder.newClient(); client.register(MyProvider1.class); // Create atm target; inherits MyProvider1 WebTarget atm = client.target("http://.../atm"); // Register MyProvider2 atm.register(MyProvider2.class); // Create balance target; inherits MyProvider1, MyProvider2 WebTarget balance = atm.path(”{cardId}/balance"); // Register MyProvider3 balance.register(MyProvider3.class);

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

16. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 16 Common Configuration - Motivation Client-side client.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(“jsonp.callback.name”, “callback”).property(“jsonp.callback.queryParam”, “true”)...

17. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 17 Common Configuration - Motivation Server-side public class MyApp extends javax.ws.rs.core.Application { public Set > getClasses() { Set > classes = new HashSet ();... classes.add(JsonMessageBodyReader.class); classes.add(JsonMessageBodyWriter.class); classes.add(JsonpInterceptor.class);... return classes; }

18. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 18 Common Configuration - Solution Client-side client.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(“jsonp.callback.name”, “callback”).property(“jsonp.callback.queryParam”, “true”)... JsonFeature jf = new JsonFeature().enableCallbackQueryParam(); client.register(jf);

19. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 19 Common Configuration - Solution Server-side public Set > getClasses() {... classes.add(JsonMessageBodyReader.class); classes.add(JsonMessageBodyWriter.class); classes.add(JsonpInterceptor.class);... } public Set > getClasses() {... classes.add(JsonFeature.class);... }

20. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 20 Common Configuration public interface Configurable { Configuration getConfiguration(); Configurable property(String name, Object value); Configurable register(...); } public interface Configuration { Set getClasses(); Map getContracts(Class componentClass); Set getInstances(); Map getProperties(); Object getProperty(String name); Collection getPropertyNames(); boolean isEnabled(Feature feature); boolean isRegistered(Object component);... }

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

22. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 22 A Feature Example public void JsonFeature implements Feature { public boolean configure(FeatureContext context) { context.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(CALLBACK_NAME, calbackName).property(USE_QUERY_PARAM, useQueryParam); return true; }

23. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 23 Dynamic Feature Server-side only public interface DynamicFeature { void configure(ResourceInfo ri, FeatureContext context); } public interface ResourceInfo { Method getResourceMethod(); Class getResourceClass(); }

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

25. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 25 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

26. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 26 Asynchronous Processing @Stateless @Path("/async/longRunning") public class MyResource { @GET @Asynchronous public void longRunningOp(@Suspended AsyncResponse ar) { ar.setTimeoutHandler(new MyTimoutHandler()); ar.setTimeout(15, SECONDS); final String result = executeLongRunningOperation(); ar.resume(result); }

27. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 27 Asynchronous Processing: Server Side public interface AsyncResponse { public void resume(Object/Throwable response); public void cancel(); public void cancel(int/Date retryAfter); public boolean isSuspended(); public boolean isCancelled(); public boolean isDone(); public void setTimeout(long time, TimeUnit unit); public void setTimeoutHandler(TimeoutHandler handler); public Collection > register(Class callback); public Map,Collection >> register(Class callback, Class... callbacks); public Collection > register(Object callback); public Map,Collection >> register(Object callback, Object... callbacks); }

28. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 28 Asynchronous Processing: Server Side @Target({ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Suspended { } public interface TimeoutHandler { void handleTimeout(AsyncResponse asyncResponse); }

29. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 29 Asynchronous Processing: Server Side public interface CompletionCallback { public void onComplete(Throwable throwable); } public interface ConnectionCallback { public void onDisconnect(AsyncResponse disconnected); }

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

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

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

33. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 33 Filters & Interceptors  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 Filter each incoming/outgoing message  Request  Request – ContainerRequestFilter, ClientRequestFilter  Response  Response – ContainerResponseFilter, ClientResponseFilter  Server-side specialties – @PreMatching, DynamicFeature

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

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

36. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 36 Filters & Interceptors A Gzip Reader Interceptor Example public class GzipInterceptor implements ReaderInterceptor { @Override Object aroundReadFrom(ReaderInterceptorContext ctx) { InputStream old = ctx.getInputStream(); ctx.setInputStream(new GZIPInputStream(old)); // wrapping => invokes the next interceptor Object entity = ctx.proceed(); ctx.setInputStream(old); return entity; }

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

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

39. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 39 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 BindingGlobal Binding Static @NameBinding Default @PreMatching Dynamic DynamicFeature N/A

40. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 40 Bindings @NameBinding @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(value = RetentionPolicy.RUNTIME) public @interface Logged {} @Provider @Logged @Priority(USER) public class LoggingFilter implements ContainerRequestFilter, ContainerResponseFilter { … }

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

42. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 42 A DynamicFeature Example Server-side only public void SecurityFeature implements DynamicFeature { public boolean configure(ResourceInfo ri, FeatureContext context) { String[] roles = getRolesAllowed(ri); if (roles != null) { context.register(new RolesAllowedFilter(roles)); }... }

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

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

45. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 45 Hypermedia Support Link: ; rel=ship, ; rel=cancel... http://.../customers/11 http://.../customers/11/address/1 http://.../products/111 2... Transitional Links Structural Links

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

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

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

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

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

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

52. Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Insert Information Protection Policy Classification from Slide 13 52 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, @BeanParam, MultivaluedHashMap, GenericType, …  DI Integration,, Java EE Security, MVC, high-level client API deferred

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

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