dev@jsr311.java.net

Re: JSR311: Draft of the JAX-RS 2.0 JSR

From: Bill de hÓra <bill_at_dehora.net>
Date: Sun, 14 Nov 2010 17:08:21 +0000

This looks good, some comments

> The most commonly requested feature for JAX-RS 2.0 is a client API:

I suspect this could take time to do well. Are we looking at an
aggressive schedule? ;)

One practical problem I've seen is that real world systems don't always
return errors in the same format as requested by the client (assuming
the app developer requested anything at all, again common). Simple
example - tomcat/jetty throwing up html error pages. We can argue this
is quality problem with the server but it's ugly on clients when it
happens and the entity binding blows up. I'd like to see something that
echoes the exception mapper on the server side of JAX-RS. Another
possibility is allocating handlers onto response codes.


> WebSocket or HTTP streaming processing of responses are out
> of scope for this JSR and will be handled in a future
> revision of JAX-RS.

I think I agree, but would like to be more precise on the requirements
before starting. Even progressive download can get called 'streaming'.
Would we will be abstracting away annoyances liked chunked encoding for
developers?

> This JSR will also make improvements
> to JSR in the area of ease of use,

Would a Form object as per Jersey, or an @Form annotation as per
RESTEasy be an option to consider? These are popular extensions and I
think it would be good to have strong support for forms handling in the
JSR especially now we're looking at stronger 'web site' support via MVC.

Bill


On Thu, 2010-11-11 at 16:24 -0800, Roberto Chinnici wrote:
> Experts,
>
> Below you'll find a draft of the JAX-RS 2.0 JSR. Since JAX-RS 1.1
> closed, we've been interacting with many of you in the community, at
> conferences and across various forums, so hopefully you won't find any
> surprising items in this draft.
>
> Please send us your comments/suggestions in the next couple of weeks. In
> parallel, we'll be working on filling in the remaining sections marked
> as TBD, including the schedule and business terms. We'd like to submit
> the JSR in early December, so as to get it approved by the JCP Executive
> Committee ahead of the year-end holidays.
>
> Please let us know if you'd like to be listed as a supporter of this JSR.
>
> Thanks,
> Roberto & Paul
>
> ========
>
> Title:
>
> JAX-RS 2.0: The Java(TM) API for RESTful Web Services 2.0
>
>
> Summary:
>
> This JSR will develop the next version of JAX-RS, the API for for
> RESTful (Representational State Transfer) Web Services in the Java Platform.
>
>
> Section 1: Identification
>
> JCP Member submitting this proposal: Oracle Corporation
>
> Name of Contact Person: Roberto Chinnici
> E-Mail Address: roberto.chinnici_at_oracle.com
> Telephone Number: +1 (415) 402-7873
> Fax Number: +1 (415) 402-7215
>
>
> Name of Specification Lead: Roberto Chinnici
> E-Mail Address: roberto.chinnici_at_oracle.com
> Telephone Number: +1 (415) 402-7873
> Fax Number: +1 (415) 402-7215
>
> Name of Specification Lead: Paul Sandoz
> E-Mail Address: paul.sandoz_at_oracle.com
> Telephone Number: +33476188109
> Fax Number: N/A
>
>
> Initial Group Membership:
>
> TBD
>
>
> Supporting this JSR:
>
> TBD
>
>
> Section 2: Request
>
> 2.1 Please describe the proposed Specification:
>
> The most commonly requested feature for JAX-RS 2.0 is a client API: many
> if not all JAX-RS implementations provide some degree of client API
> support. This JSR will define two client APIs, both compatible with the
> REST style: a low level API using a builder pattern and a higher level
> one leveraging the former. Common security mechanisms will also be
> specified. The API will not define how HTTP client implementations, such
> as HttpUrlConnection or the Apache HTTP client library, will plug into
> the API. The API will support synchronous and asynchronous response
> processing. WebSocket or HTTP streaming processing of responses are out
> of scope for this JSR and will be handled in a future revision of JAX-RS.
>
> Hypermedia is a very important feature of RESTful Web applications.
> JAX-RS 1.1 provided some basic support for building URIs but this JSR
> will define a way to easily create and process links associated with
> resources in representations either as link headers or links within the
> entity body. Similarly, on the client it will be possible to extract
> links in representations and make further requests according to those links.
>
> Model-View-Controller (MVC) is a common pattern in Web frameworks, where
> it is used predominantly by HTML-based applications. Adopting the MVC
> terminology, JAX-RS resource classes are comparable to controllers. This
> JSR will specify an MVC architecture compatible with the JAX-RS
> programing model. Java Server Pages will be specified as one type of
> view. It will be possible to plug in other view technologies, for
> example FreeMarker or StringTemplate.
>
> JAX-RS 1.1 has limited support for parameter validation. This JSR will
> make it possible to validate a set of parameters, such as form or query
> parameters, and to return a meaningful response in case validation
> fails. The primary API utilized for validation will be the Bean
> Validation API.
>
> JAX-RS 1.1 was defined before JSR-330 was specified and as a result does
> not utilize 330 annotations, such as @Inject, as effectively as it
> could. This JSR will specify closer integration with 330 annotations
> that may potentially render some existing annotations in JAX-RS, such as
> @Context, deprecated or redundant.
>
> JAX-RS 1.1 defines a synchronous request response model on the server
> side. This JSR will specify a simple asynchronous request processing
> model such that a response can be returned asynchronous to the request.
> Servlet 3.0 can be leveraged to enable such support but implementations
> may choose to use other container-specific APIs instead.
>
> In JAX-RS 1.1, content negotiation is primarily driven by the client
> using the "q" parameter in the Accept header. This JSR will add support
> for a server-side equivalent of it, "qs", to give the server more saying
> in the selected representation; the algorithm for content negotiation in
> the existing JAX-RS specification will be update so as to maintain
> determinism and compatibility across implementations.
>
> This JSR will also make improvements to JSR in the area of ease of use,
> e.g. by following the do-not-repeat-yourself principle more closely. It
> will also fix any number of bugs discovered in JAX-RS 1.1.
>
> As mentioned above, asynchronous support for HTTP long polling, Comet
> and Web Sockets is out of scope for this release. We plan to address it
> in a future revision of the JAX-RS specification.
>
>
> 2.2 What is the target Java platform? (i.e., desktop, server, personal,
> embedded, card, etc.)
>
> This specification is targeted for Java SE 6.0 or higher and Java EE 6
> or higher platforms.
>
>
> 2.3 The Executive Committees would like to ensure JSR submitters think
> about how their proposed technology relates to all of the Java platform
> editions. Please provide details here for which platform editions are
> being targeted by this JSR, and how this JSR has considered the
> relationship with the other platform editions.
>
> This JSR is targeted for inclusion in the Java EE 7 platform.
> Additionally, Java EE 6 products will be allowed to implement JAX-RS 2.0
> instead of JAX-RS 1.1.
>
>
> 2.4 Should this JSR be voted on by both Executive Committees?
>
> No. By the SE/EE EC only.
>
>
> 2.5 What need of the Java community will be addressed by the proposed
> specification?
>
> See 2.1 above.
>
>
> 2.6 Why isn't this need met by existing specifications?
>
> See 2.1 above.
>
>
> 2.7 Please give a short description of the underlying technology or
> technologies:
>
> See above.
>
>
> 2.8 Is there a proposed package name for the API Specification? (i.e.,
> javapi.something, org.something, etc.)
>
> JAX-RS 2.0 will use the same package name as JAX-RS 1.1, namely javax.ws.rs.
>
>
> 2.9 Does the proposed specification have any dependencies on specific
> operating systems, CPUs, or I/O devices that you know of?
>
> No.
>
>
> 2.10 Are there any security issues that cannot be addressed by the
> current security model?
>
> No. This JSR will leverage existing HTTP security mechanisms.
>
>
> 2.11 Are there any internationalization or localization issues?
>
> This JSR will use the I18N support in Java SE.
>
>
> 2.12 Are there any existing specifications that might be rendered
> obsolete, deprecated, or in need of revision as a result of this work?
>
> No.
>
>
> 2.13 Please describe the anticipated schedule for the development of
> this specification.
>
> TBD
>
>
> 2.14 Please describe the anticipated working model for the Expert Group
> working on developing this specification.
>
> The primary means of communication will be email, with conference calls
> and face-to-face meetings scheduled as needed. We will solicit feedback
> from the community and leverage the open source development model.
>
>
> 2.15 Provide detailed answers to the transparency checklist, making sure
> to include URLs as appropriate.
>
> JAX-RS 2.0 will follow the same working model as JAX-RS 1.0/1.1
> (JSR-311). In particular, a project site will be used to track all
> issues and disseminate information on the progress of the JSR. See
> https://jsr311.dev.java.net/ for more details on the way JAX-RS 1.0 was run.
>
> - The public can read the names of the people on the Expert Group.
>
> This information will be on on the project page for the JSR. It will
> also be part of every specification draft.
>
> - The Expert Group business is regularly reported on a publicly readable
> alias.
>
> The Expert Group will conduct business on a publicly readable alias. A
> private alias will be used only for EG-confidential information, as needed.
>
> - The schedule for the JSR is publicly available, it's current, and I
> update it regularly.
>
> The schedule will be available on the project page for the JSR.
>
> - The public can read/write to a wiki for my JSR.
>
> We'll use a public mailing list for comments.
>
> - I read and respond to posts on the discussion board for my JSR on jcp.org.
>
> We'll track such discussions and respond to them or redirect users to
> the public comment mailing list.
>
> - There is an issue-tracker for my JSR that the public can read.
>
> Yes, it will be accessible from the JSR project page.
>
> - I have spoken at conferences and events about my JSR recently.
>
> Yes, most recently at JavaOne 2010 and Devoxx 2010.
>
> - I am using open-source processes for the development of the RI and/or TCK.
>
> Yes, as Project Jersey, see https://jersey.dev.java.net/.
>
> - The Update tab for my JSR has links to and information about all
> public communication mechanisms and sites for the development of my JSR.
>
> It will point to the project page for the JSR.
>
>
> 2.16 Please describe how the RI and TCK will de delivered, i.e. as part
> of a profile or platform edition, or stand-alone, or both. Include
> version information for the profile or platform in your answer.
>
> The reference implementation will be made available standalone and also
> as part of the reference implementation for the Java EE 7 platform. The
> TCK will be made available standalone as part of the Java EE CTS.
>
>
> 2.17 Please state the rationale if previous versions are available
> stand-alone and you are now proposing in 2.13 to only deliver RI and TCK
> as part of a profile or platform edition (See sections 1.1.5 and 1.1.6
> of the JCP 2 document).
>
> N/A.
>
>
> 2.18 Please provide a description of the business terms for the
> Specification, RI and TCK that will apply when this JSR is final.
>
> TBD
>
>
> Section 3: Contributions
>
> 3.1 Please list any existing documents, specifications, or
> implementations that describe the technology. Please include links to
> the documents if they are publicly available.
>
> JAX-RS 1.1 specification, http://jcp.org/en/jsr/detail?id=311.
>
>
> 3.2 Explanation of how these items might be used as a starting point for
> the work.
>
> The JAX-RS 1.1 specification will be the starting point for this work.
>
>
> Section 4: Additional Information
>
> 4.1 This section contains any additional information that the submitting
> Member wishes to include in the JSR.
>
> N/A
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: dev-help_at_jsr311.dev.java.net
>