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.
>
> 2. The list of EG members needs to be updated as does, I suspect, the
> acknowledgements.
Agreed. Shing Wai can you please take care of that.
>
>
> HTTP Upgrade
>
> 1. I don't see why ProtocolHandler#outputReady() is required. Data is
> written to the OutputStream of the WebConnection which the container
> then writes to the client.
>
> 2. I don't think WebConnection needs to be aware that the protocol may
> support 'half closes'. Let the ProtocolHandler implementation handle
> that if it wants to.
>
> 3. The javadoc for ProtocolHandler#init() needs to be clarified that it
> is called once the HTTP Upgrade process has been completed and the
> upgraded connection is ready to start using the new protocol. It
> currently reads as if it is called when the HTTP Upgrade process starts.
>
> 4. It looks very much like a Blocking IO style is being used. That
> strikes me as rather too restrictive.
>
>
> 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?
>
> 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.
>
> 3. Are multiple ReadListeners permitted for a single ServletRequest? If
> not, setReadListener would be a better method name.
No. We can change the name of the method.
>
> 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.
>
> 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.
- Rajiv
>
> Mark