On 3/5/12 3:24 PM, 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.
>
>>
>> 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.
I mean a different issue at that time. The concern that I raised on
11/21/2011 in the first proposal is about ServletReponse has
ServletOutputStream getOutputStream();
PrinterWriter getWriter();
ServletWriter getServletWriter();
At that time, I suggest the following:
ServletWriter getWriter();
For the buffer size issue, JDK 7 only has streams, but not reader/writer
async IO API.
One may need to scan the buffer and decode to compute the buffer size in
case of chars.
Shing Wai Chan
>
>>
>> 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