JAX-RS.Next(): JAX-RS 2 and Beyond

Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Public1

JAX-RS.Next(): JAX-RS 2 and BeyondReza RahmanJava EE/GlassFish [email protected]@reza_rahman


JAX-RS Example

@Path("/atm/{cardId}")public class AtmService {

@GET @Path("/balance") @Produces("text/plain") public String balance( @PathParam("cardId") String card, @QueryParam("pin") String pin) { return Double.toString(getBalance(card, pin)); }

...


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); }}


JAX-RS Annotations


JAX-RS Annotations (Continued)

Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Public6Copyright © 2012, Oracle and/or its affiliates. All rights reserved. Public

JAX-RS 2

Client API

Modularized Configuration

Asynchronous Processing

Filters/Interceptors

Hypermedia Support

Server-side Content Negotiation


Client API


Client API

// Get instance of ClientClient client = ClientBuilder.newClient();

// Get account balanceString bal = client.target("http://.../atm/{cardId}/balance") .resolveTemplate("cardId", "111122223333") .queryParam("pin", "9876") .request("text/plain").get(String.class);


Client API

// Withdraw some moneyMoney money = client.target("http://.../atm/{cardId}/withdrawal") .resolveTemplate("cardId", "111122223333") .queryParam("pin", "9876") .request("application/json") .post(text("50.0"), Money.class);


Modularized Configuration


Modularized Configuration - Motivation

client .register(JsonMessageBodyReader.class) .register(JsonMessageBodyWriter.class) .register(JsonpInterceptor.class) .property(“jsonp.callback.name”, “callback”) .property(“jsonp.callback.queryParam”, “true”) ...

Client-side


Modularized Configuration - Motivation

public class MyApp extends javax.ws.rs.core.Application { public Set<Class<?>> getClasses() { Set<Class<?>> classes = new HashSet<…>(); ... classes.add(JsonMessageBodyReader.class); classes.add(JsonMessageBodyWriter.class); classes.add(JsonpInterceptor.class); ... return classes; }}

Server-side


Modularized Configuration - Solution

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);

Client-side


Common Configuration - Solution

public Set<Class<?>> getClasses() { ... classes.add(JsonMessageBodyReader.class); classes.add(JsonMessageBodyWriter.class); classes.add(JsonpInterceptor.class); ...}

public Set<Class<?>> getClasses() { ... classes.add(JsonFeature.class); ...}

Server-side


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; }}


Dynamic Feature

public interface DynamicFeature { void configure(ResourceInfo ri, FeatureContext context);}

public interface ResourceInfo { Method getResourceMethod(); Class<?> getResourceClass();}

Server-side only


Asynchronous Processing


Asynchronous Processing: Server-side

@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); }}


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<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);}


Asynchronous Processing: Client-side

WebTarget target = client.target("http://.../balance”)… // Start async call and register callbackFuture<?> handle = target.request().async().get( new InvocationCallback<String>() { void complete(String balance) { … } void failed(InvocationException e) { … } }); // After waiting for too long…if (!handle.isDone()) handle.cancel(true);


Filters/Interceptors


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



public class RequestLoggingFilter implements ContainerRequestFilter {

@Override public void filter(ContainerRequestContext requestContext) { log(requestContext); // non-wrapping => returns without invoking the next filter }

...}

A Logging Filter Example



Invoked ONLY when/if entity processing occurs

– Performance boost

Wrapping interceptor chain– Each interceptor invokes the next

one in the chain via context.proceed()

Intercept entity providers

MessageBodyReader interceptor

– ReaderInterceptor interface

MessageBodyWriter interceptor

– WriterInterceptor interface



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; }}

A GZip Reader Interceptor Example


Application


Request Filter Filter

NetworkTransport

…

…Response FilterFilter

write(…)

WriterInterceptor

…MBW

read(…) - optional

…MBR

WriterInterceptor

ReaderInterceptor

ReaderInterceptor


Response

Application


Filter Filter

Network

…ResponseFilterFilter

write(…)

…MBW Writer

InterceptorWriter

Interceptor

Filter Filter…

RequestRequest

read(…) - optional

ReaderInterceptor

…MBR

ReaderInterceptor

Filter Filter

Resource Matching

@PreMatching


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 Global Binding

Static @NameBindingDefault

@PreMatching

Dynamic DynamicFeature N/A


Bindings

@NameBinding@Target({ElementType.TYPE, ElementType.METHOD})@Retention(value = RetentionPolicy.RUNTIME)public @interface Logged {}

@Provider@Logged@Priority(USER)public class LoggingFilter implements ContainerRequestFilter, ContainerResponseFilter

{ … }


Bindings

@Path("/greet/{name}")@Produces("text/plain")public class MyResourceClass {

@Logged @GET public String hello(@PathParam("name") String name) { return "Hello " + name; }}


A DynamicFeature Example

public void SecurityFeature implements DynamicFeature {

public boolean configure(ResourceInfo ri, FeatureContext context) { String[] roles = getRolesAllowed(ri);

if (roles != null) { context.register(new RolesAllowedFilter(roles)); } } ...}

Server-side only


Hypermedia Support


Hypermedia

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> <item> <product>http://.../products/111</product> <quantity>2</quantity> </item> <items> ... </order>


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();


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); … }


Content Negotiation


Server Side Content Negotiation

GET http://.../widgets2Accept: text/*; q=1...

Path("widgets2")public class WidgetsResource2 { @GET @Produces("text/plain", "text/html") public Widgets getWidget() {...}}


Server Side Content Negotiation

GET http://.../widgets2Accept: text/*; q=1...

Path("widgets2")public class WidgetsResource2 { @GET @Produces("text/plain; qs=0.5", "text/html; qs=0.75") public Widgets getWidget() {...}}


Try it Out!

http://dlc.sun.com.edgesuite.net/glassfish/4.0.1/promoted/


JAX-RS 2 Implementations

TomEE

GlassFish


JAX-RS.next

CDI alignment Server-Sent Events (SSE) More Hypermedia (Structural Links) Action-Oriented Web Framework? Higher level client API? Fixes and clarifications


Summary

Major improvements– Client API– Modularized Configuration– Asynchronous Processing– Filters/Interceptors– Hypermedia Support– Server-side Content Negotiation

Many minor API improvements– Bean Validation, Request / Response, URI builder, String Converters, @BeanParam, MultivaluedHashMap, GenericType, etc

JAX-RS.next spinning up now!


Learning More

Jersey User Guide– https://jersey.java.net/documentation/latest/user-guide.html

JAX-RS Transparent Expert Group– http://jax-rs-spec.java.net

Java EE 7 Reference Implementation– http://glassfish.org

JAX-RS Reference Implementation– https://jersey.java.net

The Aquarium– http://blogs.oracle.com/theaquarium

JAX-RS.Next(): JAX-RS 2 and Beyond

Technology

Transcript of JAX-RS.Next(): JAX-RS 2 and Beyond