of 48 /48
1 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. JAX-RS 2.0: RESTful Java on Steroids Arun Gupta, Java EE & GlassFish Guy http://blogs.oracle.com/arungupta , @arungupta

JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

Embed Size (px)

DESCRIPTION

The purpose of this technical session is to elaborate on all the new features being discussed in JAX-RS 2.0. The most commonly requested feature for JAX-RS 2.0 is a client API. Client APIs can range from low-level, just above HttpURLConnection, to high-level, often including support for IoC and hyperlinking. Other features this presentation covers are hypermedia, MVC, validation, interceptors, improved content negotiation, and better integration with other specifications such as JSR 330.

Citation preview

Page 1: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Page 2: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

2 Copyright © 2011, 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.

Page 3: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Part I: How we got here ?

Page 4: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

How We Got Here?

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

Page 5: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 6: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

JAX-RS 1.0 Goals

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

Page 7: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 8: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 9: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Requested Features

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg MVC

Hypermedia

Page 10: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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!

Page 11: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Part II: Where We Are Going

Page 12: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg MVC

Hypermedia✔

✔✗

Page 13: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIInterceptors

/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

Page 14: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 15: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 16: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 17: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 18: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 19: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIInterceptors

/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔

Page 20: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 21: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 22: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Filter Example: LoggingFilter

@Providerclass LoggingFilter implements RequestFilter, ResponseFilter {

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

Page 23: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Filter Example: LoggingFilter (contd.)

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

}

Page 24: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 25: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 26: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Client

Order of execution

RequestFilter

WriteToHandler

ReadFromHandler

ResponseFilter

Server

RequestFilter

ReadFromHandler

WriteToHandler

ResponseFilter

Page 27: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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 { … }

Page 28: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Binding Example: LoggingFilter

@Path("/")public class MyResourceClass {

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

Page 29: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia✔

✔✔

Page 30: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 31: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 32: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 33: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 34: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

Page 35: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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>

Page 36: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 37: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 38: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 39: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔

Page 40: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Motivation

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

• Link types:• Structural Links• Transitional Links

Page 41: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 42: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 43: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

New in JAX-RS 2.0

Client APIFilters/Handlers

Async

Validation

JSR 330

ImprovedConneg

Hypermedia

✔✔

✔✔

Page 44: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Improved Conneg

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

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

Page 45: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 46: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Other Topics Under Consideration

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

• High-level client API?

Page 47: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

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

Page 48: JAX-RS 2.0: RESTful Java on Steroids, by Aron Gupta

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

Q&A