dev@jsr311.java.net

New sketch of updated APIs

From: Marc Hadley <Marc.Hadley_at_Sun.COM>
Date: Thu, 19 Apr 2007 14:21:05 -0400

See:

https://jsr311.dev.java.net/sketches/sketch2/overview-summary.html

I started with the previous sketch[1] and switched it to use a
builder pattern for responses as originally suggested by Dhanji,
handling of input data is the same for both. Here's a brief list of
the changes:

- Coalesced the SPI packages into a single new package
- Removed Representation<T> and JAXBRepresentation
- Made Response into an abstract builder class, removed subclasses
(TemporaryRedirect etc) and moved it to the core package (no longer
any separate response package)
- Removed annotations that are no longer needed (@HttpStatus,
@EntityBody)
- Removed response header stuff from HttpHeaders

For comparison, here are a few examples that show the two approaches
in action.

(i) Method that returns a statically-typed entity using default
status (200 OK).

@HttpMethod
@ProduceMime("application/widgets+xml")
Widget getWidget() {
   Widget w = ...
   return w;
}

The above works using either approach.

(ii) Method that returns a dynamically-typed entity using default status

// annotation driven
@HttpMethod
Representation getWidget() {
   Widget w = ...
   return new Representation<Widget>(w, "application/widgets+xml");
}

// using builder
@HttpMethod
Response getWidget() {
   Widget w = ...
   return Response.representation(w, "application/widgets+xml");
}

(iii) Method that creates a new statically-typed resource and returns
a representation of it

// annotation driven
@HttpMethod("POST")
@ProduceMime("application/widgets+xml")
Response addWidget(...) {
   Widget w = ...
   URI widgetId = ...
   Representation<Widget> r = new Representation<Widget>(w,
"application/widgets+xml");
   return new Created(r, widgetId);
}

// using builder
@HttpMethod("POST")
@ProduceMime("application/widgets+xml")
Response addWidget(...) {
   Widget w = ...
   URI widgetId = ...
   return Response.created(w, widgetId);
}

(iv) Method that creates a new dynamically-typed resource and returns
a representation of it

// annotation driven
@HttpMethod("POST")
Response addWidget(...) {
   Widget w = ...
   URI widgetId = ...
   Representation<Widget> r = new Representation<Widget>(w,
"application/widgets+xml");
   return new Created(r, widgetId);
}

// using builder
@HttpMethod("POST")
Response addWidget(...) {
   Widget w = ...
   URI widgetId = ...
   return Response.created(w, widgetId).type("application/widgets+xml");
}

Note that, for the examples above, the differences from a user
perspective between our initial proposal and sketch 1 are pretty
minimal, the impact on an implementation is the main difference as
outlined in an earlier mail[2].

Having played with it a little I think I prefer the builder approach,
its very flexible for fine tuning a response and the static methods
of Response maintain the simplicity of creating a particular kind of
response that contains all the necessary metadata.

Marc.

[1] https://jsr311.dev.java.net/servlets/ReadMsg?list=dev&msgNo=233
[2] https://jsr311.dev.java.net/servlets/ReadMsg?list=dev&msgNo=253

---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.