Hi Sean,
Many thanks for your comments. Marc and I will process and respond to
them as quick as possible.
Paul.
On May 24, 2008, at 10:22 PM, Sean Landis wrote:
> 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.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jsr311.dev.java.net
> For additional commands, e-mail: users-help_at_jsr311.dev.java.net
>