I have some comments on the draft, but first an introduction. I
presented a session at JavaOne entitled "It's all about the SOA:
RESTful Service-Oriented Architecture at Overstock.com," with my
colleague Ian Robertson. Afterwards, Marc Hadley and Paul Sandoz
introduced themselves and later Paul asked me to comment on the draft
spec. So that's where this is coming from.
Regards
Sean
Configuration through ApplicationConfig
Is there any way to tighten up the getResourceClasses() and
getProviderClasses() to return something more specfic than sets of
<Class<?>>?
Page 5, line 17. "MAY" seems weak for multiple endpoint types.
On page 5, line 23, I think it is a bad idea to depend on another spec
to define how something fundamental as publishing a Provider in Java
SE is done. That said, I am unfamiliar with JAX-WS. Personally, I
think Spec interdependencies are dangerous and should be avoided in
general. If this spec takes the position of leveraging JAX-WS then
there should be an up-front section explaining where and why this is
done.
Page 10, line 13, what does "closest matching provider" mean? How is
closeness determined?
Page 10, line 30, what is the "declared metadata?" Seems like this
should be more clearly specified.
Page 11, lines 2 - 4. I do not understand the distinction between the
first and last paragraphs that refer to anchoring. This needs
clarification - maybe it is simply redundant.
Page 11 and 12, Section 3.4.1, discussion of subresources is
confusing. To clarify, change page 11, line 36 to be HTTP request
method designator.
Page 12, 32 & 33. Should @ProduceMime and @ConsumeMime be reversed to
be analogous in order to request and response? That is: "Application
classes can declare the supported request and response media types
using @ConsumeMime and @ProducedMime, respectively."
Page 12, Section 3.5. The section would be improved by expanding the
example to include @ConsumeMime.
Page 12, line 8. What would happen if @ProduceMime("text/html")
decorated the getWidget method. It seems like there should be an
error.
Page 15, footnote. I suggest using a less esoteric wording. I have no
idea what an "Explicitly platonic method" is. Does it mean that I have
declared that I love it in a non-sexual way?
Are there other forms of content negotiation supported other than URI-based?
Page 15, line 12. It would be better to use "Effective URI" instead of
"preprocessed request URI" for consistency. See Table 3.1.
Page 16 and multiple occurrences. Capturing group needs to be defined.
Page 19, line 21 & 22. I would prefer that constructors with the same
number of parameters either not be allow or be undefined. This avoids
unanticipated compatibility issues.
Page 20, line 17. Put a space or a "." between "MessageBodyReader" and
"ReadFrom."
The JavaDoc for MessageBodyReader/Writer are hard to understand. An
example would be very helpful.
Page 21, line 8. Put a space or a "." between "MessageBodyWriter" and "write."
Page 22, 4.3.6. I don't understand how the application-supplied entity
providers are hooked into the processing chain. For example, if I want
to encrypt content, do I extend every Entity Provider my application
uses to do this? It seems like encoding should be parameterized
somehow.
Page 22, section 4.5. It is unclear what the purpose is. The
corresponding JavaDoc is also vague.
End of Chapter 5. There is a blank page.
Section 6.2. I don't think this section belongs in the document.