JAX RS 2.0 - OTN Bangalore 2013

JAX-RS 2.0
A New Standard in RESTful Web Services Development
Jagadish Ramu
Application Server Group
Oracle
Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

The following is intended to outline our general product direction. It is intended
for information purposes only, and may not be incorporated into any contract.
It is not a commitment to deliver any material, code, or functionality, and should
not be relied upon in making purchasing decisions. The development, release,
and timing of any features or functionality described for Oracle’s products
remains at the sole discretion of Oracle.

Agenda
l REST? What? Why?
l JAX-RS 1.1 – The Good, The Bad, The Missing
l JAX-RS 2.0 – New Standard for RESTful Web
l Services in Java
l Client API
l Asynchronous HTTP processing
l Filters & Interceptors

Why REST
Architectural style constraints which… …translate to system design properties
Client-server
Statelessness
Uniform Interface
Cacheability
Layering
Code on Demand
Scalability
Simplicity
Evolvability, Extensibility
Reliability
Performance, Efficiency
Visibility

Why REST
l HTTP is the Web communication standard
l Support for HTTP-based I/O in all modern platforms & languages
l Hassle-free Interoperability
l Zero Footprint – Mobile device friendly
l Uniform set of HTTP methods
l Easy to understand and consume services
l Data Representation Independence
l Services tailored to the client needs

JAX-RS - Java API for RESTful Services
Standard annotation-driven API
that aims to help developers
build RESTful Web services and
their clients in Java
l POJO-Based Resource
l Classes
l Programming model
agnostic
l HTTP Centric
l Maps HTTP requests to
Java method invocations
l Entity Format Independence
l Container Independence
l Included in Java EE

JAX-RS Resources
public class OrderResource {
public List<Order> getOrders() { … }
public Order getOrder(String orderId,
String from) { … }
public CustomerResource customer(…) { … }
…
}

JAX-RS Resources
@Path(“orders”)
@Path(“{id}”)
@Path(“{id}/customer”)
…
}

JAX-RS Resources
@Path(“orders”)
@GET
@GET
@Path(“{id}”)
…
}

JAX-RS Resources
@Produces(“application/xml, text/plain”)
@Consumes(“application/xml”)
@Path(“orders”)
@GET
@GET
@Path(“{id}”)
…
}

JAX-RS Resources
@Produces(“application/xml, text/plain”)
@Path(“orders”)
@GET
@GET
@Path(“{id}”)
public Order getOrder(@PathParam(“id”) String orderId,
@HeaderParam(“From”) @Default(“unknown”) String from) { …
}
…
}

JAX-RS 2.0 Client API
l Motivation
l HTTP client libraries too low level
l Leveraging existing features of JAX-RS 1.x server API
l Entity providers, etc.
l Provided by most major JAX-RS 1.x implementations
l Need for a standard
l Fluent API
l Client Builder  Client  Web Target  …  Request building 
Response
l URI templating
l Configuration inheritance & specialization

Main Client API Components
l ClientBuilder
l Bootstrapping client runtime
l Client
l Main API entry point
l Connection management, configurable
l WebTarget
l URI, URI template abstraction (“glorified URI”)
l Configurable

Accessing a service
Client client = ClientBuilder.newClient();

Accessing a service
WebTarget ordersTarget = client.target(“http://example.com/eshop/orders”);

Accessing a service
WebTarget orderTarget = ordersTarget.path(“{id}”);

Accessing a service
WebTarget orderTarget = ordersTarget.path(“{id}”);
Order order = orderTarget.resolveTemplate(“id”, “1234”)
.request(“application/xml”)
.get(Order.class);

Accessing a service
Order newOrder = new Order(…);
Response response = ordersTarget.request(“text/plain”)
.post(Entity.xml(newOrder));

Accessing a service
Response response = ordersTarget.request(“text/plain”)
if (response.getStatus() == 200) {
String orderId = response.readEntity(String.class);
Link invoiceLink = response.getLink(“invoice”);
client.target(invoiceLink).request()…
}

Future-based Async Client API
Future<Message> msg
= client.target(“http://example.com/messenger”)
.async()
.get(Message.class);
while (!msg.isDone()) {
// do something else…
}
display(msg.get());

Callback-based Async Client API
client.target(“http://example.com/messenger”)
.async()
.get(new InvocationCallback<Message>() {
public void completed(Message msg) {
display(msg);
}
public void failed(Throwable t) { … }
});
// do something else…

Asynchronous JAX-RS Services
l Blocking or long-running operations
l Off-load HTTP I/O container thread
l Detach a request processing thread from response
l Represent a suspended client connection in API
l Suspend until a response is available
l Resume when the response is ready
l Leverage Servlet 3.x async support (if available)

Asynchronous Processing: Server-side
@Path(“messenger”)
public class MessengerResource {
public static Queue<AsyncResponse> messageQueue = …;
@GET
@Produces(“application/xml”)
public void getMessage(@Suspended AsyncResponse ar) {
ar.setTimeoutHandler(new MyTimeoutHandler());
ar.setTimeout(15, SECONDS);
messageQueue.put(ar);
}
…

…
@POST
public void postMessage(Message msg) {
AsyncResponse ar = messageQueue.take();
ar.resume(msg);
}
}

Suspended
resume(…)/cancel(…)
Running Responding Completed
Timing out
TimeoutHandler
onTimeout(…)
setTimeout(…)
resume(…)/cancel(…)
CompletionCallback
onComplete(…)

JAX-RS 2.0 Filters & Interceptors
l Advanced use-cases
l For framework, library or advanced developers
l Customize JAX-RS request/response processing
l Logging, Compression, Security, Etc.
l Introduced for client and server APIs
l Replace existing proprietary support
l Provided by most JAX-RS 1.x implementations
l All using slightly different types or semantics

JAX-RS 2.0 Filters
l Non-wrapping filter chain
l Filters do not invoke next filter in the chain
directly
l managed by the JAX-RS runtime
l Each filter decides to proceed or break
the chain (abortWith in RequestFilters)
l Request Processing
l ContainerRequestFilter
l ClientRequestFilter
l Response Processing
l ContainerResponseFilter
l ClientResponseFilter

A Logging Filter Example
public class RequestLoggingFilter implements ContainerRequestFilter {
@Override
public void filter(ContainerRequestContext requestContext) {
log(requestContext);
// non-wrapping => returns without invoking the next filter
}
private void log(ContainerRequestContext requestContext) { … }
}

JAX-RS 2.0 Interceptors
l Invoked ONLY if needed
l when/if entity processing occurs
l Performance boost
l Wrapping interceptor chain
l Each interceptor invokes the next one in the
chain via context.proceed()
l MessageBodyReader interceptor
l ReaderInterceptor interface
l MessageBodyWriter interceptor
l WriterInterceptor interface

A GZip Reader Interceptor Example
public class GzipInterceptor implements ReaderInterceptor {
@Override
public 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;
}
}

Binding Filters and Interceptors
l Associating filters and interceptors with resource methods
l Default binding
l Applied to every request / response
l Custom binding
l @NamedBinding
l DynamicFeature

Named Binding
@NameBinding
public @interface Logged {}
@Logged
@BindingPriority(USER)
public class LoggingFilter
implements ContainerRequestFilter, ContainerResponseFilter { … }

Named Binding
@Path("/greet/{name}")
@Produces("text/plain")
public class MyResourceClass {
@Logged
@GET
public String hello(@PathParam("name") String name) {
return "Hello " + name;
}
}

Dynamic Feature
public interface DynamicFeature {
void configure(ResourceInfo ri, FeatureContext context);
}
public interface ResourceInfo {
Method getResourceMethod();
Class<?> getResourceClass();
}

Dynamic Feature
public void SecurityFeature implements DynamicFeature {
public boolean configure(ResourceInfo ri, Configuration config) {
String[] roles = getRolesAllowed(ri);
if (roles != null) {
config.register(new RolesAllowedFilter(roles));
}
}
…
}

Client Pipeline
Application
write(…)
Writer
Interceptor … MBW
Request Filter Filter
Transport Network
…
Response Filter … Filter
read(…) - optional
MBR …
Writer
Interceptor
Reader
Interceptor
Reader
Interceptor

Server Pipeline
Request Filter … Filter Request
Response
Application
Filter Filter
Network
Filter … Filter Response
write(…)
MBW Writer …
Interceptor
Writer
Interceptor
read(…) - optional
Reader
Interceptor … Reader MBR
Interceptor
Filter Filter
Resource
Matching
@PreMatching

JAX-RS 2.0 Summary
l Major new features
l Client API, Filters & Interceptors, Asynchronous support, Common
Configuration, Hypermedia
l Many API improvements and extensions
l Request / Response, UriBuilder, ParamConverter,
@BeanParam, MultivaluedHashMap, GenericType, …
l Improved TCK coverage = improved portability
l ~350 tests in JAX-RS 1.x, ~2300 tests in JAX-RS 2.0

Jersey 2 – JAX-RS 2.0 RI
l New code-base, repackaged (org.glassfish.jersey)
l Unfortunately, incompatible with Jersey 1.x proprietary APIs
l Contribution-friendly (github.com/jersey/jersey)
l Support for all the new JAX-RS 2.0 features & more
l Server-sent Events & Chunked data
l Dynamic Resource Modeling
l Standard Java Dependency Injection API support
l Including the ability to define custom injection bindings

Q A

On the Web
l JAX-RS
l Project web site jax-rs-spec.java.net
l Users mailing list users@jax-rs-spec.java.net
l JSR-339 site jcp.org/en/jsr/detail?id=339
l Jersey
l Project web site jersey.java.net
l Users mailing list users@jersey.java.net
l Twitter @gf_jersey

Graphic Section Divider
More JAX-RS 2.0 Features

Hypermedia in RESTful Applications
 REST principles
l Identifiers and Links
l HATEOAS (Hypermedia As The Engine Of App State)
 Link types:
l Structural Links
l Transitional Links

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

JAX-RS 2.0 Hypermedia Enhancements
 Link and LinkBuilder classes
l RFC 5988: Web Linking
 Support for Link in ResponseBuilder and filters
l Transitional links (headers)
 Support for manual structural links
l Via Link.JaxbAdapter & Link.JaxbLink
 Create a resource target from a Link in Client API

Producing Links (Server-side)
Link self = Link.fromResourceMethod(MyResource.class, ”handleGet”)
.build();
Link update = Link.fromResourceMethod(MyResource.class, “handlePost”)
.rel(”update”)
.build();
...
Response res = Response.ok(order)
.link("http://.../orders/1/ship", "ship")
.links(self, update)
.build();

Consuming Links (Client-side)
// Consumer API (client-side)
Response orderResponse = ordersTarget.request(“text/plain”)
Link shipmentLink = orderResponse.getLink(“ship”);
if (shipmentLink != null) {
Response shipment = client.target(shipmentLink).post(…);
…
}

Server Side Conneg
GET http://.../widgets HTTP/1.1
Accept: text/*; q=1.0
…
@Path("widgets2")
public class WidgetsResource {
@GET
@Produces("text/plain", "text/html") // ???
public Widgets getWidget() {...}
}

Server Side Conneg
GET http://.../widgets HTTP/1.1
Accept: text/*; q=1.0
…
@Path("widgets2")
public class WidgetsResource {
@GET
@Produces("text/plain,qs=0.5", "text/html,qs=0.75") // !!!
public Widgets getWidget() {...}
}

JAX-RS Exceptions
 WebApplicationException
l RedirectionException (3xx)
l getLocation():URI
l ClientErrorException (4xx)
l BadRequestException (400), NotAuthorizedException (401),
ForbiddenException (403), NotFoundException (404),
NotAllowedException (405), NotAcceptableException (406),
NotSupportedException (415)
l ServerErrorException (5xx)
l InternalServerErrorException (500), ServiceUnavailableException
(503)

JAX-RS Exceptions

Working with JAX-RS Exceptions
try {
Order order = orderTarget.request(“application/xml”)
.get(Order.class);
} catch (RedirectionException ex) {
// we have to look elsewhere
client.target(ex.getLocation()).request()…
} catch (ServerErrorException ex) {
// it’s not our fault the request failed, let’s retry later…
} catch (ClientErrorException ex) {
// definitely our fault, let’s see if we can fix the request and retry…
}

Server-Sent Events
: an example of a SSE event
id: 1
event: text-message
data: Hello, this is a
data: multi-line message.
<blank line>

Server-sent Events in Jersey
Server side Client side
OutboundEvent
EventOutput
SseBroadcaster
BroadcasterListener
InboundEvent
EventInput
EventSource
EventListener

SSE Server-side
@Path("message/stream")
public class MessagesResource {
private static SseBroadcaster broadcaster = new SseBroadcaster();
@GET
@Produces(SseFeature.SERVER_SENT_EVENTS)
public EventOutput getMessageStream() {
final EventOutput eventOutput = new EventOutput();
broadcaster.add(eventOutput);
return eventOutput;
}
…

SSE Server-side
…
private static AtomicLong nextMessageId = new AtomicLong(0);
@PUT
@Consumes(MediaType.APPLICATION_JSON)
public void putMessage(Message message) {
OutboundEvent event = new OutboundEvent.Builder()
.id(String.valueOf(nextMessageId.getAndIncrement()))
.mediaType(MediaType.APPLICATION_JSON_TYPE)
.data(Message.class, message)
.build();
broadcaster.broadcast(event);
}
}

SSE Client-side – IoC Model
EventSource eventSource = new EventSource(target.path("message/stream")) {
@Override
public void onEvent(InboundEvent event) {
String name = event.getName();
Message message = event.readData(Message.class);
display(name, message);
}
};
…
eventSource.close();

SSE Client-side – Pull Model
EventInput events = target.path("message/stream")
.request().get(EventInput.class);
while (!stop) {
InboundEvent event = events.read();
String name = event.getName();
Message message = event.readData(Message.class);
display(name, message);
}
events.close();

JAX RS 2.0 - OTN Bangalore 2013

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (20)

Similaire à JAX RS 2.0 - OTN Bangalore 2013

Similaire à JAX RS 2.0 - OTN Bangalore 2013 (20)

Plus de Jagadish Prasath

Plus de Jagadish Prasath (6)

Dernier

Dernier (20)

JAX RS 2.0 - OTN Bangalore 2013