JAX-RS 2.0: What’s New in JSR 339 ?

JAX-RS 2.0: What’s New in JSR 339 ?
Arun Gupta, Java EE & GlassFish Guy
http://blogs.oracle.com/arungupta, @arungupta

Tokyo 2012
De 4 à 6 de Abril de 2012

San Francisco 2012
De 30 de Setembro à 4 de Outubro de 2012


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
Resources

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

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

…

HTTP Method Built-in
Binding Serialization


Example: JAX-RS API (contd.)
… Custom Serialization

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


Requested Features

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg MVC


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 published on Nov 1, 2011!


Part II: Where We Are Going


New in JAX-RS 2.0
✔
✔ Filters/Handlers
Client API
✔
Hypermedia
✔ ✔
Async JSR 330
✔
Validation
Improved
✔
✗
Conneg MVC


New in JAX-RS 2.0

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


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


Client API

Resource Target
Client Factory Client
“atm”

Configuration Resource Target
Configuration
Configuration “{cardId}”

Resource Target Resource Target
Invocation Request Builder
“balance” “withdrawal”

Response


Example: Client API

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

Can also inject @URI for the target ß

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


Example: Client API (contd.)

// Withdraw some money
Money 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();
}
});


Example: Configuration
// Get client and register MyProvider1
Client client = ClientFactory.newClient();
client.configuration().register(MyProvider1.class);

// Create atm and register MyProvider2
// Inherits MyProvider1 from client
Target atm = client.target("http://.../atm");
atm.configuration().register(MyProvider2.class);

// Create balance and register MyProvider3
// Inherits MyProvider1, MyProvider2 from atm
Target balance = atm.path("balance"); // new instance
balance.configuration().register(MyProvider3.class);


New in JAX-RS 2.0

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


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
@Provider
class 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)
logResponse(ctx.getResponse());
return FilterAction.NEXT;
}

}


Handlers

•  Wrapping extension points
•  ReadFrom: Interface ReadFromHandler
•  WriteTo: Interface WriteToHandler

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


Handler Example: GzipHandler
@Provider
class GzipHandler implements ReadFromHandler, WriteToHandler
{

@Override
public Object readFrom(ReadFromHandlerContext ctx)
if (gzipEncoded(ctx)) {
InputStream old = ctx.getInputStream();
ctx.setInputStream(new GZIPInputStream(old));
}
return ctx.proceed();
}
… }

Binding

•  Associating filters and handlers with resource methods
•  Same mechanism for filters and handlers

Name Binding Global Binding

@NameBinding/
Static DEFAULT
@Qualifier?

DynamicBinding DynamicBinding
Dynamic
interface Interface


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

@Provider
@Logged
@BindingPriority(USER)
public 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

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


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)
Built-in public void registerUser(
@NotNull @FormParam("firstName") String fn,
Custom
@NotNull @FormParam("lastName") String ln,
@Email @FormParam("email") String em) {
... }
}


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
@CheckUser1
class 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

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


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 URI
Target target = client.target("http://.../atm/balance")…

// Start async call and register callback
Future<?> 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

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


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 Transitional
...
<order id="1">
<customer>http://.../customers/11</customer>
<address>http://.../customers/11/address/1</customer>
<items>
<item> Structural

<product>http://.../products/111</products>
<quantity>2</quantity>
</item>
... </order>


Current Proposal
Transitional Links Only
•  Link and LinkBuilder classes
•  RFC 5988: Web Linking

•  Support for Link in ResponseBuilder
•  Create Target from Link in Client API


Example: Using Transitional Links
// Server API
Response res = Response.ok(order)
.link("http://.../orders/1/ship", "ship")
.build();

// Client API
Response 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

Filters/Handlers
Client API

Hypermedia
Async JSR 330

Validation
Improved
Conneg


Improved Conneg

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

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


Improved Conneg (contd.)

GET http://.../widgets2
Accept: 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: users@jax-rs-spec.java.net
•  All EG discussions forwarded to this list


Q&A


JAX-RS 2.0: What’s New in JSR 339 ?

Recommended

Recommended

More Related Content

What's hot

What's hot (19)

Viewers also liked

Viewers also liked (20)

Similar to JAX-RS 2.0: What’s New in JSR 339 ?

Similar to JAX-RS 2.0: What’s New in JSR 339 ? (20)

More from Arun Gupta

More from Arun Gupta (20)

Recently uploaded

Recently uploaded (20)

JAX-RS 2.0: What’s New in JSR 339 ?