java summit chennai: jax-rs 2.0
DESCRIPTION
Java Summit Chennai: JAX-RS 2.0TRANSCRIPT
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
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.
3 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Part I: How we got here ?
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
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
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
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-in Serialization
Resources
URI Parameter Injection
HTTP Method Binding
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
Param Binding
9 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Requested Features
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
MVC
Hypermedia
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!
11 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Part II: Where We Are Going
12 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
MVC
Hypermedia ✔
✔
✔
✔
✔
✔
✔ ✗
13 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API Interceptors
/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia
✔
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
15 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Client API
Client Resource Target “atm”
Request Builder
Resource Target “{cardId}”
Resource Target “balance”
Resource Target “withdrawal”
Client Factory
Response
Invocation
Configuration Configuration Configuration
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);
Param Binding
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);
Param Binding
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"));
Param Binding
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(); } });
Param Binding
20 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Example: Configuration
Param Binding
// Get client and register MyProvider1Client client = ClientFactory.newClient();client.configuration().register(MyProvider1.class);// Create atm and register MyProvider2// Inherits MyProvider1 from clientTarget atm = client.target("http://.../atm");atm.configuration().register(MyProvider2.class);// Create balance and register MyProvider3// Inherits MyProvider1, MyProvider2 from atmTarget balance = atm.path("balance"); // new instancebalance.configuration().register(MyProvider3.class);
21 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API Interceptors
/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia
✔ ✔
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
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
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; } …
Param Binding
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; } }
Param Binding
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()
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(); } … }
28 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Client
Order of execution
Request Filter
WriteTo Handler
ReadFrom Handler
Response Filter
Server
Request Filter
ReadFrom Handler
WriteTo Handler
Response Filter
29 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Binding
• Associating filters and handlers with resource methods • Same mechanism for filters and handlers
Name Binding Global Binding
Static @NameBinding/
@Qualifier? DEFAULT
Dynamic DynamicBinding interface
DynamicBinding Interface
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 { … }
Param Binding
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; }}
Param Binding
32 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia ✔
✔
✔ ✔
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
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) { ... } }
Param Binding
Custom
Built-in
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 … } }
Param Binding
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) { … } }
Param Binding
37 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia
✔
✔
✔
✔
✔
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>
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 } … }
Param Binding
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 } … }
Param Binding
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);
Param Binding
42 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia
✔ ✔
✔
✔
✔
✔
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
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>
Param Binding
Transitional
Structural
45 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Current Proposal
• Link and LinkBuilder classes • RFC 5988: Web Linking
• Support for Link in ResponseBuilder• Create Target from Link in Client API
Transitional Links Only
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); … }
47 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
New in JAX-RS 2.0
Client API
Filters/Handlers
Async
Validation
JSR 330
Improved Conneg
Hypermedia
✔ ✔
✔
✔ ✔ ✔
✔
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() {...}}
Param Binding
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() {...}}
Param Binding
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?
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
52 Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Q&A