Subject: Ajax requests and lifecycle mapping
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.Title: Web Services for Remote Portelts - HTTP Client API
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.
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.
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.
This specification recommends the following mechanisms to encode state within URLs of each fragment/data generating request:
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.
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.
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.
[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.