Subject: Re: [wsrp] Ajax requests and lifecycle mapping
Hi Subbu, so the model would be: - for consumer state changing operations use POST XPR(action/render/resource URL) - for state changes that do not affect the consumer and only the target portlet use POST XHR(resource URL) - for non-state changing operations use GET XHR(resource URL) seems a bit complex to me. 5.2. - should also list resource URLs - should say something about new portlet modes and window states set on the URL, do we want to allow setting those on the URL and if yes, what would be the semantic? 5.3. - I think that updating portlets that received an event is a too hard requirement, what if the portlet is not on the current page? I would propose to change the MUST to a SHOULD 5.4. - it should also note that changes done by the pbia should be reflected when sending events and the event should carry the updated values Stefan Subbu Allamaraju wrote: > At last week's JSR286 EG F2F, two proposals for processing fragment > requests were discussed. > > The first one is based on what we have discussed in the WSRP TC so far, > i.e mapping of blockingAction URLs to pbia, and render URLs to > getMarkup. In both these cases, the data/markup fragment generated by > the producer is meant for consumption by the portlet on the user-agent. > > The second one is a mapping of *all* fragment requests to pbia, > effectively disregarding the type of the URL. > > It was argued that the second one provides a simpler API for portlet > developers as well developers of portlet bridges. > > I took a quick stab at mapping the second proposal to the WSRP > lifecycle. Please find it attached. > > Subbu > _______________________________________________________________________ > Notice: This email message, together with any attachments, may contain > information of BEA Systems, Inc., its subsidiaries and affiliated > entities, that may be confidential, proprietary, copyrighted and/or > legally privileged, and is intended solely for the use of the individual > or entity named in this message. If you are not the intended recipient, > and have received this message in error, please immediately return this > by email and then delete it. > > ------------------------------------------------------------------------ > > > 5. Request Processing > > While the XMLPortletRequest interface provides a convenient means for > portlets to use ECMAScript and the like to request for data or markup > fragments, as described in this section, Producers and Consumers must > take additional steps to support this interface within the WSRP 2.0 > protocol. Although this specification recommends that XMLPortletRequest > be used as the transport mechanism between user agents and Consumers, > the refinements in this section are designed such that other unspecified > transport mechanisms may be used. > > Portlets submitting requests via XMLPortletRequest intend to receive > data and/or markup fragments generated by the portlet/Producer via the > responseXML or responseText fields of XMLPortletRequest and process > them. This is unlike requests submitted directly due to user > interactions (e.g. by sumitting a form or activating a link), where the > portlet is not expected to process the response. > > Another charactersistic of portlets using XMLPortletRequest is that > portlets may use this interface to update one or several parts of their > user-interface markup using one or more requests from the user-agent to > the Consumer. In addition, portlets need to continue to generate their > full markup (i.e. not fragments) for aggregation by the Consumer. While > processing requests and generating markup, portlets need to be able to > distinguish between each of these requests. However, portlets can not > rely on the publicValues or opaqueValue parts of the navigationalContext > to distinguish between multiple requests originating from the same > portlet. In WSRP 2.0, the navigationalContext is scoped to each portlet, > and hence will be common across multiple requests originating for the > same portlet. Again, this is unlike requests submitted via traditional > means where the Consumer updates the Portlet's complete markup, and not > parts there of. > > This section describes the refinements/additions made to the WSRP 2.0 > protocol required to support XMLPortletRequest. > > > 5.1. Refinements to the Three-Step Protocol > > The three-step protocol in WSRP 2.0 is designed primarily to isolate > non-idempotent action/event processing from idempotent rendering. This > seperation allows Producers to generate markup for portlets whenever > requested by Consumers to do so. This also allows to Consumers to > completely regenerate the aggregated page upon processing state changing > performBlockingInteraction and handleEvents steps of the three-step > protocol. However, for requests to generate data or markup fragments for > consumption by portlets, e.g. through an XMLPortletRequest, such a > seperation is not necessary. Portlets can process interaction requests > and generate data or markup fragments within a single phase. > Accordingly, this specification refines the three-step protocol as follows. > > 1. Whenever a portlet uses XMLPortletRequest to submit requests to > the Consumer, the Consumer SHOULD send a > performBlockingInteraction request to the Producer for the portlet > that originated the XMLPortletRequest. The Consumer MUST include > the element requestType with a value of fragmentRequest as an > extension to the markupParams element. This element is defined in > the urn:oasis:names:tc:wsrp:extra namespace and is of type > QNamedString. Note that some Producers may be able to derive this > information without relying on this Consumer-supplied extension, > e.g. by encoding relevant information into the > wsrp-interactionState or wsrp-extensions parameters of the URL > that intiated the request. The extension element requestType is > designed to assist those Producers that can not derive this > information on their own. > 2. While processing the performBlockingInteraction request, if the > Producer/portlet intends any data/markup fragments to be made > available via the responseText or responseXML attributes of the > XMLPortletRequest, the Producer/portlet MUST include such markup > within the markupContext element of the response. > 3. While processing a performBlockingInteraction, a portlet may > generate events causing the Consumer to initiate one or several > handleEvents requests. > 4. While processing the XMLPortletRequest, if the Consumer sends > getMarkup requests to the Producer for the portlet that originated > the XMLPortletRequest, the Producer/portlet MUST generate markup > for aggregation by the Consumer. Consumers MUST NOT make the > generated markup available via the responseText or responseXML > fields of the XMLPortletRequest. > 5. While processing the XMLPortletRequest, if the Consumer sends > getMarkup requests to Producers for any portlet other than the one > that originated the XMLPortletRequest, such Producers/portlets > MUST generate markup for aggregation by the Consumer. Consumers > MUST NOT make the generated markup available via the responseText > or responseXML fields of the XMLPortletRequest. > > Of these, the first step allows a portlet to use one or more instances > of XMLPortletRequest to manage one or more parts of its user interface > while other requests can continue to initiate the three-step protocol as > specified in WSRP 2.0, and cause full markup generation of each portlet. > > Since XMLPortletRequest can only make text and or XML content available > via its responseXML and responseText fields, for those > performBlockingInteraction and getMarkup requests that contain the > requestType extension with a value of fragmentRequest, the Consumer MUST > include corresponding MIME types in the array of mimeTypes element of > the markupParams element. The MIME types sent to the Producer MUST NOT > prevent it from returning markup with text or XML type. > > > 5.2. State Management > > This specification recommends the following mechanisms to encode state > within URLs of each fragment/data generating request: > > 1. If the portlet is using a URL of type blockingAction to call the > open method of the XMLPortletRequest, the portlet can encode > request-specific state within the interactionState or > wsrp-extensions parameters encoded in the URL. > 2. If the portlet is using a URL of type render to call the open > method of the XMLPortletRequest, the portlet can encode > request-specific state within the wsrp-extensions parameter > encoded in the URL. > > Upon processing a performBlockingInteraction or getMarkup request with a > value of fragmentRequest for the requestType extension, in order to > provide consistent user experience, Producers are encouraged to update > the portlet's navigational state and/or session state. This will ensure > that markup generated in response to future performBlockingInteraction > or handleEvents or getMarkup requests will reflect all user interactions > performed via previous XMLPortletRequest submissions. > > Consumers that manage the navigationalContext of portlets on the client > (e.g. by encoding in URLs or storing in cookies) must note that such > state may become stale after processing any XMLPortletRequest. Upon each > invokation of the XMLPortletRequest, in order to provide a consistent > user experience, such Consumers MUST update client-side encoded state > either by modifying the encoded state (e.g. by update each URL or by > sending additional cookies) or by regenerating the complete page or by > using some unspecified implementation-specific means. > > > 5.3. Event Processing > > Portlets using XMLPortletRequest can receive and generate events during > the Consumer's processing of the XMLPortletRequest as per WSRP 2.0. > Consumers supporting event-based coordination feature of WSRP 2.0 are > encouraged to support the same while processing XMLPortletRequests. > > During the Consumer's processing of an XMLPortletRequest, if the > Consumer supports event-based coordinaton while processing > XMLPortletRequests, portlets other than the one that initiated the > request may be able to participate in the handleEvents portion of the > three-step protocol. Since such portlets may update their own state > (navigational, session or persistent) during event processing, Consumers > MUST update the markup of such portlets in the aggregated page. > > If the portlet that initiated the XMLPortletRequest is the target of a > handleEvents request, the Consumer may discard the data or markup > fragment generated during the previous performBlockingInteraction and > request that the portlet generate its full markup for aggregation. In > such cases, or anytime when a Consumer decides to discard the data or > markup fragment generated, the Consumer MUST NOT transition the value of > the readyState field of the XMLPortletRequest beyond a value of 2 > (Sent), and MUST set the values of the responseText and responseXML > fields to undefined. > > > 5.4. Public Navigational State > > In WSRP 2.0, the publicValues portion of the navigationalContext is > another means of achieving consumer-mediated coordination (Section 3.10 > of WSRP 2.0). This feature can also cause portlets other than the one > initiated the XMLPortletRequest receive updates to their publicValues > portion of their navigationalContext, which can influence their markup > generation. Consumers are encouraged to update the markup of such > portlets in the aggregated page. > > > 5.5. Asynchronous Requests > > [This should be in the primer, IMO. Comments?] > > It is common for portlets to use XMLPortletRequest for asynchronous > communication between the user agents and Consumers, i.e. by calling the > open function with a value of true for the boolean argument async. > However, when more than one instance of XMLPortletRequest is used to > submit requests from within the same portlet or multiple portlets either > at the same time or in quick succession, the resulting view of the > Consumer's aggregated page may be inconsistent with the end-user's > expectations. > > In order to improve the user experience, Consumers are encouraged to > provide adequate visual indicators to end users during the processing of > each XMLPortletRequest indicating that an asynchrnous request is in process. > > Portlets are also encouraged to design the user interface such that > users are aware of the asynchrous requests in progress, and provide > visual indicators of any negative consequences of initiating new > requests while the current request is in process. > > _______________________________________________________________________ > Notice: This email message, together with any attachments, may contain > information of BEA Systems, Inc., its subsidiaries and affiliated > entities, that may be confidential, proprietary, copyrighted and/or > legally privileged, and is intended solely for the use of the individual > or entity named in this message. If you are not the intended recipient, > and have received this message in error, please immediately return this > by email and then delete it.