[jsr-314-open] [ajax] My AI on PartialResponseWriter.

[Jim Driscoll]

Below, here's a description of the changes I'd like to make to the 
PartialResponseWriter - describing the problem, and the changes that I'd 
like to make in broad detail.

This is one of the AIs I had from our Ajax breakout meeting.


Please comment within a day or two, I'll write up a formal proposal with 
the exact proposed language to go in once I know I'm not spinning my 
wheels on a DOA idea.

To save time, section 4 is the only part you may have a problem with - 
since it's the only part that changes current behavior...  but we do 
have to address the issue somehow, so if you hate this idea, please 
propose another that also works...


Jim

----------

Problem Description:

PartialResponseWriter has very little JavaDoc or spec associated with 
it.  Users are finding it difficult to use as a result.  Additionally, 
the implicit call to startUpdate means that writing out other XML 
directives from a custom component is quite difficult.

The JavaDoc preample says:

PartialResponseWriter decorates an existing ResponseWriter to support 
the generation of a partial response suitable for Ajax operations. In 
addition to the markup generation methods inherited from 
javax.faces.context.ResponseWriter, this class provides methods for 
constructing the standard partial response elements.
The individual method summaries say such things as:
void startUpdate(String targetId)

Write the start of an update operation.
And
void startEval()

Write the start of an eval operation.
And
void startDocument()

Write the start of a partial response.

Currently, what to do if you were to call a startXXX method while 
already in a startXXX method is unspecified.

The spec (section 13.4.4.1) simply says:
Writing The Partial Response
JavaServer Faces provides javax.faces.context.PartialResponseWriter to 
ensure the Ajax response that is written follows the standard format as 
specified in Section 1.3 “XML Schema Definition for Partial Responses” 
Implementations must take care to properly handle nested CDATA sections 
when writing the response. PartialResponseWriter decorates an existing 
ResponseWriter implementation by extending 
javax.faces.context.ResponseWriterWrapper. Refer to the 
javax.faces.context.PartialResponseWriter JavaDocs, and the JavaScript 
documentation for the jsf.ajax.response function for more specifics.

Proposal:

We need to tighten up the spec in several ways:
1) Add comments to the JavaDoc that PartailResponseWriter will typically 
have startDocument and startUpdate called before the component can get 
ahold of it.  Note that this is to allow interoperability with 
components that are not instrumented for Ajax.
2) Expand description in 13.4.4.1 to describe that an error will be 
thrown if:

startDocument is called more than once on a response.
any method is called after endDocument.
any method is called before startDocument

3) Add a description to the spec of what methods will typically be 
called before the client receives the PartialResponseWriter in 
RenderResponse.  Describe when this is not so (render = @none).

4) Allow for the calling of other methods besides startUpdate within a 
normal component’s Render Response.
	a) I propose that we treat all calls to the following methods as having 
their content placed on a queue, to be written out after the endUpdate 
is called:
		delete
		redirect
		startEval/endEval
		startUpdate/endUpdate
		startExtension/endExtension
		startInsertBefore/endInsert
		startInsertAfter/endInsert
		startError/endError
		updateAttributes
	b) nesting is only one deep - i.e., since the startUpdate is already 
called, if you call startEval, it will be an error to call anything 
other than endEval before calling any other method from this list...

5) Update JavaDoc to indicated paired methods -
		startEval/endEval
		startUpdate/endUpdate
		startExtension/endExtension
		startInsertBefore/endInsert
		startInsertAfter/endInsert
		startError/endError
	It will be an error, and an exception will be thrown, to call one 
method without the other.


Concluding statement:

While the description of this behavior (in particular the queuing) may 
be a little difficult, I believe that this behavior most closely matches 
what users are expecting when they currently use the API.  If this 
approach is accepted by the EG, I’ll write up the formal changes.