OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

wsrp-interfaces message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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

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.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]