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

[Ken Paulsen]

4b - Why not add them to the queue described in 4a instead of throwing 
an exception (of course detect loops)?

Separate but related: I would like to override the behavior of 
PartialResponseWriter.  How is this currently pluggable?  I have 
discussed this a couple times with Ryan and have a solution working 
currently where I simply call 
PartialViewContext.setPartialRequest(false) early enough in the 
lifecycle, then do what I need... it's a hack, though.  The server-side 
is written to match the JS handling on the client-side... I would like 
formal ways documented in the spec to customize the behavior on the 
server and the JS on the client.

Thanks,

Ken


Jim Driscoll wrote:
> 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.