JAX-RS 2.0: RESTful Web services on steroids

1 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.

JAX-RS 2.0: RESTful Java on Steroids

Arun Gupta, Java EE & GlassFish Guyhttp://blogs.oracle.com/arungupta, @arungupta

http://blogs.oracle.com/arungupta



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.


Part I: How we got here ?


How We Got Here?

• Shortest intro to JAX-RS 1.0• Requested features for JAX-RS 2.0• JSR 339: JAX-RS 2.0


JAX-RS Origins

• JAX-RS 1.0 is Java API for RESTful WS• RESTFul Principles:– Assign everything an ID– Link things together– Use common set of methods– Allow multiple representations– Stateless communications


JAX-RS 1.0 Goals

• POJO-Based API• HTTP Centric• Format Independence• Container Independence• Inclusion in Java EE


Example: JAX-RS API

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

…

Built-inSerialization

Resources

URI ParameterInjection

HTTP MethodBinding


Example: JAX-RS API (contd.)

…

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

Custom Serialization


Requested Features

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg MVC

Hypermedia


JSR 339 Expert Group

• EG Formed in March 2011• Oracle Leads: Marek Potociar / Santiago Pericas-G.• Expert Group: – Jan Algermissen, Florent Benoit, Sergey Beryozkin (Talend),

Adam Bien, Bill Burke (RedHat), Clinton Combs, Bill De Hora, Markus Karg, Sastry Malladi (Ebay), Julian Reschke, Guilherme Silveira, Dionysios Synodinos

• Early Draft 2 published on Feb 9, 2012!


Part II: Where We Are Going


New in JAX-RS 2.0


Async

Validation

JSR 330

ImprovedConneg MVC

Hypermedia✔

✔

✔

✔

✔

✔

✔✗


New in JAX-RS 2.0

Client APIInterceptors

/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔


Motivation

• HTTP client libraries too low level• Sharing features with JAX-RS server API• E.g., MBRs and MBWs

• Supported by some JAX-RS 1.0 implementations• Need for a standard


Example: Client API

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

Can also inject @URI for the target

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


Example: Client API (contd.)

// Withdraw some moneyMoney mon = client.target("http://.../atm/withdraw") .pathParam("card", "111122223333") .queryParam("pin", "9876") .request("application/json") .post(text("50.0"), Money.class);


Example: Generic Interface (Command pattern, Batch processing)Invocation inv1 = client.target("http://.../atm/balance")… .request(“text/plain”).buildGet();

Invocation inv2 = client.target("http://.../atm/withdraw")… .request("application/json") .buildPost(text("50.0"));


Example: Generic Interface (contd.)

Collection<Invocation> invs = Arrays.asList(inv1, inv2);

Collection<Response> ress = Collections.transform(invs, new F<Invocation, Response>() { public Response apply(Invocation inv) { return inv.invoke(); } });


New in JAX-RS 2.0

Client APIInterceptors

/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔


Motivation

• Customize JAX-RS implementations via well-defined extension points

• Use Cases: Logging, Compression, Security, Etc.• Shared by client and server APIs• Supported by most JAX-RS 1.0 implementations• All using slightly different types or semantics


Filters

• Non-wrapping extension points• Pre: Interface RequestFilter• Post: Interface ResponseFilter

• Part of a filter chain• Do not call the next filter directly• Each filter decides to proceed or break chain• By returning FilterAction.NEXT or FilterAction.STOP


Filter Example: LoggingFilter

@Providerclass LoggingFilter implements RequestFilter, ResponseFilter {

@Override public FilterAction preFilter(FilterContext ctx) throws IOException { logRequest(ctx.getRequest()); return FilterAction.NEXT; }

…


Filter Example: LoggingFilter (contd.)

@Override public FilterAction postFilter(FilterContext ctx) throws IOException { logResponse(ctx.getResponse()); return FilterAction.NEXT; }

}


Interceptors

• Wrapping extension points• ReadFrom: Interface ReaderInterceptor• WriteTo: Interface WriterInterceptor

• Part of a interceptor chain• Call the next handler directly• Each handler decides to proceed or break chain• By calling ctx.proceed()


Handler Example: GzipInterceptor@Providerclass GzipInterceptor implements ReaderInterceptor, WriterInterceptor {

@Override public Object aroundreadFrom(ReadInterceptorContext ctx) throws IOException { if (gzipEncoded(ctx)) { InputStream old = ctx.getInputStream(); ctx.setInputStream(new GZIPInputStream(old)); } return ctx.proceed(); } … }


Client

Order of execution

RequestFilter

WriteToHandler

ReadFromHandler

ResponseFilter

Server

RequestFilter

ReadFromHandler

WriteToHandler

ResponseFilter


Binding Example: LoggingFilter

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

@Provider@Loggedpublic class LoggingFilter implements RequestFilter, ResponseFilter { … }


Binding Example: LoggingFilter

@Path("/")public class MyResourceClass {

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


New in JAX-RS 2.0


Async

Validation

JSR 330

ImprovedConneg

Hypermedia✔

✔

✔✔


Motivation

• Services must validate data• Bean Validation already provides the mechanism• Integration into JAX-RS

• Support for constraint annotations in:• Fields and properties• Parameters (including request entity)• Methods (response entities)• Resource classes


Example: Constraint Annotations

@Path("/")class MyResourceClass {

@POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public void registerUser( @NotNull @FormParam("firstName") String fn, @NotNull @FormParam("lastName") String ln, @Email @FormParam("email") String em) { ... } }

Custom

Built-in


Example: User defined Constraints

@Target({ METHOD, FIELD, PARAMETER })@Retention(RUNTIME)@Constraint(validatedBy = EmailValidator.class)public @interface Email { ... }

class EmailValidator implements ConstraintValidator<Email, String> { public void initialize(Email email) { … } public boolean isValid(String value, ConstraintValidatorContext context) { // Check 'value' is e-mail address … } }


Example: Request Entity Validation

@CheckUser1class User { ... }

@Path("/")class MyResourceClass { @POST @Consumes("application/xml") public void registerUser1(@Valid User u) { … }

@POST @Consumes("application/json") public void registerUser12(@CheckUser2 @Valid User u) { … } }


New in JAX-RS 2.0


Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔

✔

✔

✔

✔


Motivation

• Let “borrowed” threads run free!• Container environment

• Suspend and resume connections• Suspend while waiting for an event• Resume when event arrives

• Leverage Servlet 3.X async support (if available)• Client API support• Future<RESPONSE>, InvocationCallback<RESPONSE>


Example: Suspend and Resume

@Path("/async/longRunning")public class MyResource { @Context private ExecutionContext ctx;

@GET @Produces("text/plain") public void longRunningOp() { Executors.newSingleThreadExecutor().submit( new Runnable() { public void run() { Thread.sleep(10000); // Sleep 10 secs ctx.resume("Hello async world!"); } }); ctx.suspend(); // Suspend connection and return } … }


Example: @Suspend Annotation@Path("/async/longRunning")public class MyResource { @Context private ExecutionContext ctx;

@GET @Produces("text/plain") @Suspend public void longRunning() { Executors.newSingleThreadExecutor().submit( new Runnable() { public void run() { Thread.sleep(10000); // Sleep 10 secs ctx.resume("Hello async world!"); } }); // ctx.suspend(); Suspend connection and return } … }


Example: Client API Async Support

// Build target URITarget target = client.target("http://.../atm/balance")… // Start async call and register callbackFuture<?> handle = target.request().async().get( new InvocationCallback<String>() { public void complete(String balance) { … } public void failed(InvocationException e) { … } }); // After waiting for a while …If (!handle.isDone()) handle.cancel(true);


New in JAX-RS 2.0


Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔

✔

✔

✔

✔


Motivation

• REST principles• Identifiers and Links• HATEOAS (Hypermedia As The Engine Of App State)

• Link types:• Structural Links• Transitional Links


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

Transitional

Structural


Example: Using Transitional Links

// Server APIResponse res = Response.ok(order) .link("http://.../orders/1/ship", "ship") .build(); // Client APIResponse order = client.target(…) .request("application/xml").get();

if (order.getLink(“ship”) != null) { Response shippedOrder = client .target(order.getLink("ship")) .request("application/xml").post(null); … }


New in JAX-RS 2.0


Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔

✔

✔

✔✔

✔


Improved Conneg

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

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


Improved Conneg (contd.)

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() {...}}


Other Topics Under Consideration

• Better integration with JSR 330• Support @Inject and qualifiers

• High-level client API?


More Information

• JSR: http://jcp.org/en/jsr/detail?id=339• Java.net: http://java.net/projects/jax-rs-spec• User Alias: [email protected]• All EG discussions forwarded to this list

http://jcp.org/en/jsr/detail?id=339

http://java.net/projects/jax-rs-spec

mailto:[email protected]


Q&A

Technology

JAX-RS 2.0: RESTful Web services on steroids