Thanks for the careful review. Disposition of comments inline below.
On May 24, 2008, at 4:22 PM, Sean Landis wrote:
>
> Configuration through ApplicationConfig
> Is there any way to tighten up the getResourceClasses() and
> getProviderClasses() to return something more specfic than sets of
> <Class<?>>?
>
Already discussed in this thread. I'll update the javadoc to explain
why the return type is so loose.
> Page 5, line 17. "MAY" seems weak for multiple endpoint types.
>
We don't want to require all implementations of the JSR to support SE-
based endpoints, e.g. an implementation might only support Servlet-
based deployment. I think MAY is the only reasonable choice here.
> 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.
>
JAX-WS is part of Java SE 6, so depending on it is no worse than
depending on any other JDK class. JAX-WS defines an SE-based mechanism
for publishing services and this part of the spec defines how a JSR
311 application is published using that mechanism. We don't require
support for producing a JAX-WS Provider for the reasons stated above
and because even if an implementation does support SE-based endpoints,
requiring JAX-WS still might not make sense. Restlet is a good example
of an implementation for which supporting JAX-WS would be unnecessary.
> Page 10, line 13, what does "closest matching provider" mean? How is
> closeness determined?
>
Updated the text to be more explicit.
> Page 10, line 30, what is the "declared metadata?" Seems like this
> should be more clearly specified.
>
This is a reference to the JSR 311 annotations on the class. E.g. an
automated response to an OPTIONS request can determine the supported
HTTP methods by examining the resource method designators on the
methods of the resource class. I'll update the spec to be more explicit.
> 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.
>
They are a little redundant, the first was meant to encompass sub-
resource locators as well as root resources but I think it will be
clearer to leave that till later.
> 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.
>
OK, I'll reword.
> 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."
>
Yes.
> Page 12, Section 3.5. The section would be improved by expanding the
> example to include @ConsumeMime.
>
I'll do that.
> Page 12, line 8. What would happen if @ProduceMime("text/html")
> decorated the getWidget method. It seems like there should be an
> error.
>
Correct. That would only work if there was a provider that supported
the Widget type and text/html.
> 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?
>
Hehe. I was using the term from the RESTful Web Services book but I
guess I should have explained that better. Actually this is likely to
go away pending resolution of another issue.
> Are there other forms of content negotiation supported other than
> URI-based?
>
Yes, the standard Accept header is also supported, in fact URI based
conneg is preprocessed to use the Accept header internally, section
3.7.1 gives details.
> Page 15, line 12. It would be better to use "Effective URI" instead of
> "preprocessed request URI" for consistency. See Table 3.1.
>
OK.
> Page 16 and multiple occurrences. Capturing group needs to be defined.
>
OK.
> 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.
>
I've added issue 40 (
https://jsr311.dev.java.net/issues/show_bug.cgi?id=40
) to track this.
> Page 20, line 17. Put a space or a "." between "MessageBodyReader" and
> "ReadFrom."
>
OK.
> The JavaDoc for MessageBodyReader/Writer are hard to understand. An
> example would be very helpful.
>
OK.
> Page 21, line 8. Put a space or a "." between "MessageBodyWriter"
> and "write."
>
OK.
> 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.
>
Application-supplied entity providers have higher priority that
implementation-supplied ones. So if you want to override an existing
entity provider you just include an equivalent one (same supported
Java and media types) with the application.
> Page 22, section 4.5. It is unclear what the purpose is. The
> corresponding JavaDoc is also vague.
>
OK, I'll add some more explanatory text.
> End of Chapter 5. There is a blank page.
>
> Section 6.2. I don't think this section belongs in the document.
>
Its a placeholder, expect it to change as Java EE 6 moves along.
Thanks again,
Marc.
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.