users@servlet-spec.java.net

[servlet-spec users] [jsr340-experts] Re: Candidate for Servlet 3.1 Early draft review

From: Mark Thomas <markt_at_apache.org>
Date: Tue, 06 Mar 2012 13:56:53 +0000

On 05/03/2012 23:24, Rajiv Mordani wrote:
> Hi Mark,
> See comments in-line -
>
> On 3/5/2012 1:27 PM, Mark Thomas wrote:
>> On 28/02/2012 19:19, Shing Wai Chan wrote:
>>> I have enclosed the candidate Servlet 3.1 Early draft review with change
>>> bars and the associated javadoc.
>>> The source code can be found at
>>> https://svn.java.net/svn/glassfish~svn/trunk/api/javaee-api/javax.servlet
>>> .
>>> For a list of changes, please look at the status chapter.
>>> Please give us feedback by Mar 6 (next Tue).
>>>
>>> Shing Wai Chan and Rajiv Mordani
>> General
>>
>> 1. I really don't like that the Javadoc is no longer part of the
>> specification documentation. Given that there is important detail that
>> is only present in the Javadoc I think that it should be included so
>> that all the necessary information is available in a single document. A
>> PDF is also a lot easier to search (e.g. for a method name) than a PDF
>> plus a bunch of HTML files. It might be more work for the EG lead, but
>> it would be a big benefit to the users of the specification.
>
>
> The specification consists of two parts - the pdf and javadocs. I am not
> sure
> that including it in the spec itself helps too much other than when you
> print the
> spec you get the javadoc as well.

The help is when you are searching the specification for information on
the behaviour of a particular method. It is easier to search a single
document rather than one document and a bunch of HTML files.

>> Async IO
>>
>> 1. No timeout support.
>
>
> I asked Remy the same question - can you explain more about what kind of
> timeout support are you looking for? Time out from what? Can you give an
> example of what you would like to see in the API?

I think Remy has already answered that and I agree with his answer.

>> 2. Why is it illegal to call read() if isReady() returns false? If the
>> application wants to block waiting for data, let it.
>
> Well if you block when trying to read then why not just use the blocking
> API? If
> there is a good use case then I am open to relaxing that restriction.

I was thinking about this in the context of Tomcat's three connectors -
one of which uses blocking IO (BIO). There are reasons why a user may
prefer the BIO connector. Async IO can't work with BIO with the
restriction in place.

Lifting the restriction seems to be the simplest solution.

>> 4. Why do we need ServletRequest#getServletReader()? Especially since
>> there is no way to control the buffer size.
>
> Well this was raised I think by Shing Wai in the EG that there is an
> asymmetry between
> the Request and Response in that we had a getReader but no getWriter and
> no one objected so we added it.

I guess I am still neutral on adding it, but I'd like to see the ability
to control the buffer size.

>> 5. When is onWritePossible() meant to be called? It could be called
>> almost continually based on the current description.
>
> As I clarified to Remy's email it wouldn't be called continuously. Will
> fix the documentation
> for that.

OK.

Cheers,

Mark