Web Services for Remote Portlets 1.0 Primer · Web viewHTTP cookies are transient and may become invalid. A Producer returns this fault when the Consumer supplied cookie is no longer

Web Services for Remote Portlets 1.0 Primer Version 0.45 13 May 2004

Web Services for Remote Portlets 1.0PrimerDraft 0.510.50, 6 May 2023 12 May 2004Document identifier:

wsrp-primer-1.0 (Word)

Location:http://www.oasis-open.org/committees/wsrp

Editors:Subbu Allamaraju, BEA Systems <[email protected]>Rex Brooks, Starbourne Communications <[email protected]>

Contributors:Gil Tayar, WebCollage <[email protected]>Alan Kropp, Vignette Corporation <[email protected]>

Abstract:This is the WSRP 1.0 primer. The purpose of this document is to provide a detailed explication tutorial-oriented explanation of the main concepts of the WSRP 1.0 specification. In that sense, this is a companion document to the specification. Although this primer is not normative, its tutorial approach is intended as a guide for implementers and other technical readers. This document explains the abstractions of the specification in a “real-world” perspective based on a step by step approach representing practical use case scenarios.

Status:This version is a draft of the non-normative WSRP 1.0 primer. Comments about points needing clarification are much appreciated and may be emailed to [email protected].

If you are on [email protected] list for committee members, send comments there. If you are not on that list, subscribe to [email protected] list and send comments there. To subscribe, send an email message to [email protected] with the word "subscribe" as the body of the message.

Copyright © 2004 The Organization for the Advancement of Structured Information Standards [OASIS]

5

10

15

20

25

30

Subbu Allamaraju, 01/03/-1,

Help interpret not-so-obvious points in the spec

mailto:[email protected]





http://www.oasis-open.org/committees/wsrp

Table of Contents1 Introduction............................................................................................................................................3

2 Basic Scenario.........................................................................................................................................4

3 Service Description Interface................................................................................................................63.1 Description.......................................................................................................................................63.2 Message Format...............................................................................................................................63.3 Faults................................................................................................................................................83.4 Recommendations.............................................................................................................................8

4 Registration Interface............................................................................................................................94.1 Description.......................................................................................................................................94.2 Message Format.............................................................................................................................10

4.2.1 Registration.............................................................................................................................104.2.2 Modifying a Registration........................................................................................................134.2.3 Terminating a Registration.....................................................................................................14

4.3 Faults..............................................................................................................................................16

5 Markup Interface.................................................................................................................................175.1 Description.................................................................................................................................26175.2 Purposes Served.........................................................................................................................26175.3 Message Format.........................................................................................................................26185.4 Interaction Operations...............................................................................................................2623

5.4.1 Using InitCookie....................................................................................................................265.4.2 Releasing Sessions..................................................................................................................26

5.5 Modes and States........................................................................................................................26275.6 User Categories..........................................................................................................................26285.7 Faults..........................................................................................................................................2628

6 Portlet Management Interface........................................................................................................27286.1 Message Format.........................................................................................................................2830

6.1.1 getPortletDescription..........................................................................................................28306.2 Faults..........................................................................................................................................3638

7 Use Profiles........................................................................................................................................37387.1 Producer Levels..........................................................................................................................3739

7.1.1 Base....................................................................................................................................37397.1.2 Simple.................................................................................................................................37397.1.3 Complex.............................................................................................................................3739

7.2 Consumer Levels........................................................................................................................37397.2.1 Base....................................................................................................................................37397.2.2 Simple.................................................................................................................................38397.2.3 Complex.............................................................................................................................3840

8 Basic Topics/Issues...........................................................................................................................38408.1 Markup.......................................................................................................................................38408.2 Fault Handling...........................................................................................................................41408.3 Caching.......................................................................................................................................41418.4 Persistence..................................................................................................................................41418.5 Statefulness.................................................................................................................................41418.6 Modes/Window States.................................................................................................................42428.7 URL Rewriting............................................................................................................................42428.8 4242

9 Advanced Topics/Issues...................................................................................................................42429.1 User Profile and personalization...............................................................................................4242

Web Services for Remote Portlets 1.0 Primer Page 2 of 61

5

10

15

20

25

30

35

40

45

5

9.2 Localization and Internationalization........................................................................................43439.3 Security.......................................................................................................................................43439.4 Extensions...................................................................................................................................43439.5 Carrying custom modes..............................................................................................................43439.6 Multipart upload.........................................................................................................................4343

1 IntroductionWeb Services for Remote Portlets (WSRP) is a web services protocol for aggregating content and interactive web applications from remote sources. The objective of this primer is to help interpret the WSRP 1.0 Specification with usage scenarios and typical interactions that must happen to achieve such aggregation. There are numerous sources of high-level introductory information about WSRP 1.0, including the introductory section of the specification itself, and the WSRP White Paper [http://www.oasis-open.org/committees/download.php/2634/WSRP%20Whitepaper%20-%20rev%202.doc]. If you are the reading about WSRP for the first time, we encourage you to explore these resources before proceeding with the extended examples and explanations contained in this primer.

The guiding perspective on which WSRP specification was built should be of primary interest to potential implementers. This perspective is framed by the question of what problems WSRP is intended to solve. The specification’s procedural approach to solving these questions can be divided into a few main areas:

(a) Standard remote content protocol: As a standard remote content protocol, WSRP replaces many proprietary, product-specific solutions for aggregating remote content and interactive applications. This benefits all parties, consumers (e.g, portals), portlet developers (developers of such content and applications), and producers (applications hosting portlets) as well.Consumers (i.e. portals) and portlet developers alike.

(b) Promote rigorous portlet implementations: WSRP raises the bar of conformance for this standard in many respects for what constitutes a “good or effective” portlet implementation. The specification makes specific recommendations regarding markup fragment rules, representing statefulness, ensuring security, etc., with an eye toward maximizing the usefulness and integrity of portlet services. This is not to suggest that WSRP mandates a “one size fits all” approach.

(c) Framework for sophisticated scenarios: WSRP 1.0 is the foundation on which increasingly sophisticated implementations are to be specified. These include the ability for Consumers to customize a portlet’s content, and to create application process flows that coordinate the activities of multiple portlets, from multiple Producers.

(d) Using common WS-related standards: The plethora of standards and technologies that have relevance to the web services world presents a daunting and growing challenge to implementers, in terms of what to select and how to design a solution. Many of these end up as one-off, proprietary solutions of limited scope, with a limited shelf life. WSRP provides an integrated framework of existing and emerging standards and technologies based on sound criteria developed through a rigorous process.

WSRP builds on a few fundamental standards, most notably XML, and SOAP and WSDL, while allowing for the implementation of evolving standards, to deliver a protocol rich in abstractions and operations that web service implementers and Consumers require.

[Editorial Note: Note that this Primer is non-normative.]


5

10

15

20

25

30

35

40

45

5


Not clear

[Editorial Note: Add document style conventions here.]

2 Concepts2.1 Producers and ConsumersThe WSRP specification uses the terms Producer and Consumer to describe parties implementing the specification.

The Producer is a web service offering one or more portlets and implementing various WSRP interfaces/operations. Depending on the implementation, a producer may offer just one portlet, or may provide a runtime (or a container) for deploying and managing several portlets.

The Consumer is a web service client that invokes producer offered WSRP web services and provides an environment for users to interact with portlets offered by one or more such producers.

The nearly limitless variety of Producers and Consumers have been kept in mind in the development of WSRP, but for the purposes of a useful primer, we use necessarily simple examples, It is not our intention to address all such categories nor to replace the material in the specification which covers a wider range than a primer should. So, when you uncover your own questions, and discover that any particular question is not covered here, it is suggested that you have a copy of the specification available for quick reference.TODO: Refer to use profiles section.

2.2 Producer-Consumer-User Interaction[Editorial Note: Refer to #1.2 in spec to describe how these terms are modeled as “Actors” in the process of producing “User-Facing” presentation.]

2.3 Modes and States[Editorial Note: Just refer to #6.8 & # 6.9 in the spec? Do we need to talk about it in the primer? Rex thinks so-basic stage-setting for Basic Scenario. And some discussion in Markup Interface Section.]

2.4 Markup Generation[Editorial Note: Refer to #4.2 in spec to introduce the concept that the end product of WSRP is the Portlet rendered in client browser page]

3 Basic ScenarioThe WSRP specification uses the terms Producer and Consumer to describe parties implementing the specification.

The Producer is a web service offering one or more portlets and implementing various WSRP interfaces/operations. Depending on the implementation, a producer may offer just one portlet, or may provide a runtime (or a container) for deploying and managing several portlets.


5

10

15

20

25

30

35

5


Merge 2.1 with the next section? 2.2, 2.,3 and 2.4 are already covered in the following sections in more detail.

The Consumer is a web service client that invokes producer offered WSRP web services and provides an environment for users to interact with portlets offered by one or more such producers.

You can use WSRP to implement a very broad range of portlet Producers and Consumers. However, in this primer, for the sake of simplicity, we use simpler examples. It is not our intention to address all range of problems that can be solved by WSRP or to replace the material already in the specification. So, when you uncover your own questions, and discover that any particular question is not discussed here, we suggest suggest that you have a copy of the specification available for quick reference.

In this Primer, we use interactions between two parties, viz., P Inc (a WSRP Producer), and C Inc (a WSRP Consumer) to discuss various interactions that can be implemented using WSRP.

P Inc is a financial services company, providing services online to their customers and partners. C Inc is on online portal company, providing personalized collaboration, banking, and financial services. C Inc offers these services to end-users by subscription.

P Inc would like to host a number of applications including a web based portfolio management application. C Inc would like to offer this application to its end users via its portal pages.

In order to offer this portfolio management application to end users, C Inc and P Inc agree on the following:

(a) P Inc makes some metadata of the portfolio management application available to C Inc. C Inc. uses this metadata to prepare a page that users can use to manage their portfolios.

(b) A user of C Inc, U visits C Inc’s web site, and clicks on a link to portfolio management application.

(c) C Inc then sends a request to P Inc to get the initial view of the portfolio management application. P Inc then responds by transmitting markup (as HTML) that represents the first page of the application.

(d) C Inc then processes the returned markup and prepares it for aggregation. If the returned markup has links and forms, C Inc transforms the markup such that such links and forms, when activated return to C Inc.

(e) C Inc aggregates the markup into a page, and writes it into the response of the browser’s connection. The aggregated page is then transmitted to U.

(f) U reviews the page. U finds a form to submit a new stock symbol. U fills in the ticker symbol of a stock and other details, and submits the form.

(g) C Inc receives the request containing the form data submitted by U. Upon determining that this request is meant for the portfolio management application, C Inc sends another request to P Inc to process the user interaction.

(h) P Inc processes the user interaction request and adds the sticker symbol to U’s portfolio.(i) C Inc then sends a request to get the changed markup based on the current state of the

portfolio. P Inc generates markup and returns.(j) C Inc then repeats steps (d) and (e).(k) U receives a new page containing the updated portfolio.


5

10

15

20

25

30

35

40

45

5


Readers may not immediately get that P Inc is a WSRP Producer and that C Inc is a WSRP Consumer.

This scenario captures some of the essentials of the WSRP specifications. Instead of developing a proprietary application protocol to accomplish the above steps, P Inc and C Inc can agree to use WSRP as the protocol. In this scenario, P Inc is a WSRP Producer offering portlets, and C Inc is a WSRP Consumer consuming portlets and aggregating portlets for users to access aggregated portlet pages. The portfolio management application is a Portlet offered by the Producer.

Note: This version of the Primer will not address how C Inc may discover the web service end point offered by P Inc. as that is still being worked on the WSRP TC.

To implement this scenario, P Inc and C Inc can use WSRP to define various interactions, with P Inc implementing the following WSRP interfaces and operations:

(a) Service Description Interface: P Inc implements this interface to provide a metadata of itself and the list of portlets it offers. C Inc invokes the getServiceDescription() operation of this interface to obtain this metadata in step (a) of the above scenario.

(b) Markup Interface: To generate markup and to process interaction requests, P Inc implements the Markup Interface specified by WSRP. C Inc invokes the getMarkup() operation of this interface to obtain the portlet’s markup in steps (c) and (i), and invokes the performBlockingInteraction() operation to propagate U’s interactions to P Inc in step (g).

By implementing these interfaces, and agreeing to conform to WSRP, both P Inc and C Inc can use a standard mechanism to offer and consume portlets. In addition, P Inc can offer the same portlet to X Inc as long as X Inc adheres to WSRP, and C Inc can consume portlets offered by Y Inc provided Y Inc also implements WSRP interfaces.

The Service Description and Markup interfaces are the two required interfaces that must be implemented by any WSRP Producer. In addition to these two, WSRP specifies the following interfaces:

(a) Registration Interface: Registration interface provides an in-band mechanism for a Consumer to register with a Producer and let the Producer customize its behavior for each Consumer based on the registration information. As described in Section 5, WSRP also allows out-of-band mechanisms for registration.

(b) Portlet Management Interface: The Portlet Management interface allows Consumers to clone/destroy portlets, and also customize portlets by changing any associated properties.

In the following sections, we will discuss these interfaces in detail by considering each aspect of the above scenario. To keep the discussions focused on the purpose and usage of these interfaces, we postpone any discussion on faults to Section 10.1.

The normative WSDL of all WSRP Interface data structures can be found at http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_interfaces.wsdl. Various data types used in the following sections are defined at http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_types.xsd. Readers You are encouraged to refer to these documents for more complete descriptions of various messages presented in the following sections.


5

10

15

20

25

30

35

40

45

5

, 01/03/-1,

Any comments?

http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_types.xsd

http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_interfaces.wsdl

http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_interfaces.wsdl

4 Service Description Interface4.1 DescriptionIn order to set up a consumer to aggregate portlets offered by a producer, the consumer must first obtain a description of the producer, and the list of portlets offered by the producer. Based this information, the consumer will be able determine if it can successfully aggregate portlets offered by a producer, and setup its environment (for example, a page aggregating portlets) for such aggregation.

The getServiceDescription() operation of the Service Description Interface provides the Producer’s metadata including the list of offered portlets and their properties.

Figure 1: Getting Service Description

All portlet Producers are required to implement this operation. Usually, this is the first operation that a Consumer invokes on a Producer. This operation returns the following:[Editorial Note: Do we want to comment that Consumers may have to obtain service description often to check for changes in the service description. Producer can’t propagate such changes in WSRP1.0.]

(a) Producer Capabilities: The response of this operation indicates to the Consumer whether the Producer requires registration to access its portlets, whether the Consumer must explicitly initialize cookies for all markup related operations, the locales supported by the producer etc. We shall discuss the details of such metadata as we introduce various other WSRP interfaces. This information helps you set up a Consumer to interact with the Producer.

(b) Offered Portlets: The response of this operation also includes a list of portlets that the Producer offers. The portlet metadata includes a unique handle, modes, window states, and content types supported by the portlet, in addition to a description of the portlet. In this sense, the Producer acts as a portlet repository that the Consumer must look up to discover portlets.

4.2 Message FormatConsider the following scenario.

Scenario: C Inc would like to discover the capabilities of P Inc, and the list of portlets offered by P Inc.

Scenario 1: Discover PortletsIn order to get P Inc’s service description, C Inc must first send a getServiceDescription request to P Inc. Here is the most basic form of a getServiceDescription request that a consumer could send to a producer.


5

10

15

20

25

30

35

40

5


Use the scenario to motivate various messages. This is a general comment about all messages in the primer.


As we discuss different choices, we need to motivate the reader about those choices. May include example problems to drive the motivation.

<urn:getServiceDescription xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/></urn:getServiceDescription>

Message 1: Service Description Request

To this request, P Inc responds with a getServiceDescriptionResponse document that includes the following:

(a) Registration is not required: P Inc does not require C Inc to register before sending other WSRP requests. We shall discuss about registration in the next section.

(b) Supported Locales: P Inc supports “en” and “en-US” locales. This does not necessarily mean that portlets offered by this producer are limited to generating markup in these locales, but simply that the Producer’s metadata is available in these locales.

(c) Offered Portlets: P Inc offers a single portlet, uniquely identified by a portletHandle “portfolioManager”. The portletHandle is an opaque reference assigned by the producer, and both the consumer and the producer use this handle to refer to this portlet in all interactions. The producer and/or consumer may also associate data (such as properties) with this handle.

(d) MIME types supported: The portfolioManager portlet returns content of MIME type “text/html”. As with locales, this portlet is not limited to generating markup in this MIME type.

(e) Modes and window states supported: Modes and window states indicate the many ways a portlet may be rendered. This portlet could be rendered in the “wsrp:view” mode, and “wsrp:normal”, “wsrp:minimized”, and “wsrp:maximized” window states.

(f) Description: The description of the portfolioManager portlet also includes a description and a title. The Consumer may use these values for describing or presenting this portlet to its end users. For example, the Consumer may provide a title bar that includes this title.

Here is the message containing the above data:

<urn:getServiceDescriptionResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:requiresRegistration>true</urn:requiresRegistration> <urn:offeredPortlets> <urn:portletHandle>portfolioManager</urn:portletHandle> <urn:markupTypes> <urn:mimeType>text/html</urn:mimeType> <urn:modes>wsrp:view</urn:modes> <urn:windowStates>wsrp:normal</urn:windowStates> <urn:windowStates>wsrp:minimized</urn:windowStates> <urn:windowStates>wsrp:maximized</urn:windowStates> <urn:locales>en</urn:locales> <urn:locales>en-US</urn:locales> </urn:markupTypes> <urn:description xml:lang="en"> <urn:value>Manages portfolios</urn:value> </urn:description> <urn:title xml:lang="en"> <urn:value>Manage Your Portfolios</urn:value> </urn:title>


5

10

15

20

25

30

35

40

45

50

5


Rich: Use “wsrp:” rather than “urn:”?

</urn:offeredPortlets> <urn:locales>en</urn:locales> <urn:locales>en-US</urn:locales></urn:getServiceDescriptionResponse

Message 2: Service Description ResponseC Inc can now use this response to setup a page to aggregate this portlet, and offer that page to its users.

4.3 FaultsA consumer invoking the getServiceDescription operation must be prepared to handle the following faults:

(a) InvalidRegistration: A producer throws this fault when the registration data supplied by the consumer is not valid. As we shall see in the next section, Producers requiring registration require that the Consumer supply valid registration data in all invocations. However, since a Consumer uses the serviceDescriptionResponse to see if a producer requires registration, it may not supply the registration data with the getServiceDescription request. But when supplied, such registration data must be valid.

(b) OperationFailed: A producer throws this fault when it fails to process the getServiceDescription operation. In general, Consumers must be prepared to receive this fault on any WSRP invocation.

Refer to Section 10.110.3 for more details on the range of faults that a consumer must be prepared to handle.

4.4 RecommendationsService descriptions can vary widely from Producer to Producer. In general, a Producer offering a set of portlets to all Consumers without requiring any knowledge of the Consumer may follow the style of service description response described above.

However, in most cases, Producers and Consumers may find it necessary to customize their behavior based on certain properties of the other party. For example, P Inc may want to offer the portfolioManager portlet only to those Consumers that enter into a service contract. Another producer may want to customize its responses depending on the capabilities of the Consumer. Consumers and Producers may use the notion of registration to deal with such scenarios.

[Editorial Note: Atul to send some notes on some specific recommendations/best practices.]

5 Registration Interface5.1 DescriptionThe purpose of the registration interface is to provide a means within the protocol for a Consumer to register with a Producer. Registration allows the Producer to associate portlets and any portlet customization data with the Consumer that is interacting with it. The Producer can also use the registration context to scope the artifacts offered/created during interactions to Consumers that caused those interactions.. Note that registration is not a means of uniquely identifying a Consumer, but simply scopes the Consumer’s use of the Producer.


5

10

15

20

25

30

35

40

5


At the end of the previous chapter, make a case of registration. We need to motivate the reader about registration before getting into the Registration Interface.


Get reasons for registration. We should motivate why registration is a good ideaAlso elaborate on out-of-band aspects.


Discuss out-of-band communication that producers and consumers may go through to maintain a registration.

, 01/03/-1,

Delete?

The WSRP specification does not specify/restrict any possible application of registration. Here are some possible applications:

(a) Consumer can use registration to let the Producer know of its capabilities. The Producer can use such metadata to tailor its portlets.

(b) Producer can keep track of portlets used by each Consumer, by associating portlet customizations with the Consumer’s registration.

(c) Producer can tailor the list of portlets offered to each Consumer. For example, Producers may offer a separate set of portlets for each Consumer.

(d) Producer may offer/deny certain capabilities (such as the ability to customize or clone portlets) for a given Consumer.

Depending on the nature of services offered by the Producer and the nature of the business, registration may be as simple as sending a registration request to a Producer using the Registration interface, or may be as complex as fulfilling legal, billing and other contractual obligations to establish registration. Keeping this in mind, the WSRP 1.0 specification considers two forms of registration:

(a) In-band registration: In this process, using the Registration interface, the Consumer sends a request for registration to a Producer, along with any properties required by the Producer. If required by the Producer, the Consumer may still have to go through some out-of-band communications before being able to send such a request.

(b) Out-of-band registration: The Producer and Consumer go through Producer/Consumer specific business processes (such as other business web applications, or email or other manual means) to establish registration. Since the actual processes tend to be very specific to the Consumer and Producer, WSRP specification does not attempt to standardize these processes. Further discussion on out-of-band registration is therefore outside the scope of this Primer.

By following one of these forms of registration, the Consumer obtains a registrationContext from the Producer. The registrationContext includes a registrationHandle, and optionally some registrationState. Of these, the registrationHandle is a unique handle assigned by the Producer to the Consumer and remains unchanged during the lifetime of a Consumer’s registration with a Producer. The registrationState may contain additional persistent state of registration.

The registration interface specifies the following operations:(a) register(): To let a consumer register with a Producer. The Consumer may have to

supply certain producer-specified registration properties for registration. Upon registration, the Producer assigns a unique RegistrationContext for the Consumer. The Consumer must then supply this RegistrationContext with each request it makes to the Producer.

(b) modifyRegistration(): To let a Consumer modify an existing registration. The Consumer may supply registration properties. The Producer may not assign a new registrationHandle to the Consumer, but may return new registrationState.

(c) deregister(): To let the Consumer terminate a registration.

A Producer indicates that registration is required and that certain data is required for registration via its response to a getServiceDescription() request.


5

10

15

20

25

30

35

40

45

5

5.2 Message Format

5.2.1 RegistrationLet us now consider the following variations to Scenario 1 to see some of the details of registration.

P Inc requires that only registered Consumers can see its metadata or use any of its offered portlets. P Inc also requires a service agreement and certain contractual obligations to be fulfilled prior to registration.

C Inc enters into a service agreement with P Inc and fulfills all the necessary obligations. P Inc then issues a service ID and requires that C Inc supply C Inc’s DUNS number and the service ID for registration. Note that these transactions happen outside the scope of WSRP.

C Inc then registers with P Inc by supplying its DUNS number and the service ID.

Scenario 2: RegistrationSince P Inc now requires registration, P Inc sends the following response to the previous simple getServiceDescription() request from C Inc.

<urn:getServiceDescriptionResponse xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:requiresRegistration>true</urn:requiresRegistration> <urn:registrationPropertyDescription> <urn:propertyDescriptions type="xs:string" name="dunsNum"> <urn:label xml:lang="en"> <urn:value>DUNS Number</urn:value> </urn:label> </urn:propertyDescriptions> <urn:propertyDescriptions type="xs:string" name="serviceId"> <urn:label xml:lang="en"> <urn:value>Service ID</urn:value> </urn:label> </urn:propertyDescriptions> </urn:registrationPropertyDescription></urn:getServiceDescriptionResponse>

Message 3: Service Description Response from Producer Requiring RegistrationThe first point to note from this response is that this P Inc requires registration, and that it requires two registration properties to be supplied for registration. Beyond this, this service description response does not provide much information to the P Inc. Specifically P Inc chose to not include portlet metadata in its response.

C Inc then sends the following register request to P Inc supplying the DUNS number and service ID that was previously assigned to it by P Inc.

<urn:register xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:consumerName>C Inc</urn:consumerName>


5

10

15

20

25

30

35

40

45

5

<urn:consumerAgent>C Inc Portal.1.0</urn:consumerAgent> <urn:methodGetSupported>false</urn:methodGetSupported> <urn:registrationProperties xml:lang="en" name="dunsNum"> <urn:stringValue>CIncDuncNumber</urn:stringValue> </urn:registrationProperties> <urn:registrationProperties xml:lang="en" name="serviceId"> <urn:stringValue>CIncServiceID</urn:stringValue> </urn:registrationProperties></urn:register>

Message 4: Registration RequestIn addition to the registration properties, the consumer sends some additional properties of the consumer itself:

(a) Consumer name: Name of the consumer(b) Consumer agent: Name and version of the consumer(c) Method GET support: A boolean to indicate if the consumer can aggregate markup

containing forms with method GET.

Refer to the WSRP specification for a list of other optional data that the Consumer can supply during registration.

The Producer P Inc validates this request for registration, creates a registration context, and returns the following response:

<urn:registerResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle></urn:registerResponse>

Message 5: Registration Response

In this response, the registrationContext represents a registration relationship between the P Inc and C Inc, and contains a registrationHandle assigned to C Inc by P Inc. Once a Consumer obtains a registrationContext, the consumer must supply the registrationContext with all subsequent requests to the Producer. For this reasons, the Consumer must persistently maintain the registrationContext for all future invocations.

If the Producer is capable of managing persistent storage of registration data, the Producer may just create a registrationHandle and return the same in the registrationContext as shown above. However, if the Producer is not capable of managing persistent storage of registration data, the Producer may choose to send the persistent state of registration as registrationState to the Consumer. In such cases, the Consumer would be responsible for persistently storing the registrationState along with the registrationHandle and return these to the Producer in future invocations.

Having completed the registration process, C Inc can now send another service description request to P Inc, this time supplying the registrationContext.


5

10

15

20

25

30

35

40

45

5


Bold whatever is new - DONE

<urn:getServiceDescription xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext></urn:getServiceDescription>

Message 6: Service Description Request after Registration

Upon validating the registrationContext, P Inc now sends a response that includes portlets it offers.

<urn:getServiceDescriptionResponse xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:requiresRegistration>true</urn:requiresRegistration> <urn:offeredPortlets> <urn:portletHandle>portfolioManager</urn:portletHandle> <urn:markupTypes> <urn:mimeType>text/html</urn:mimeType> <urn:modes>wsrp:view</urn:modes> <urn:windowStates>wsrp:normal</urn:windowStates> <urn:windowStates>wsrp:minimized</urn:windowStates> <urn:windowStates>wsrp:maximized</urn:windowStates> <urn:locales>en</urn:locales> <urn:locales>en-US</urn:locales> </urn:markupTypes> <urn:description xml:lang="en"> <urn:value>Manages portfolios</urn:value> </urn:description> <urn:title xml:lang="en"> <urn:value>Manage Your Portfolios</urn:value> </urn:title> </urn:offeredPortlets> <urn:requiresInitCookie>none</urn:requiresInitCookie> <urn:registrationPropertyDescription> <urn:propertyDescriptions type="xs:string" name="dunsNum"> <urn:label xml:lang="en"> <urn:value>DUNS Number</urn:value> </urn:label> </urn:propertyDescriptions> <urn:propertyDescriptions type="xs:string" name="serviceId"> <urn:label xml:lang="en"> <urn:value>Service ID</urn:value> </urn:label> </urn:propertyDescriptions> </urn:registrationPropertyDescription> <urn:locales>en</urn:locales> <urn:locales>en-US</urn:locales></urn:getServiceDescriptionResponse>

Message 7: Service Description Response after Registration

Note that this message is similar to the response shown in Message 2: Service DescriptionResponse, but has only been received after C Inc fulfilled P Inc’s registration requirements.Web Services for Remote Portlets 1.0 Primer Page 13 of 61

5

10

15

20

25

30

35

40

45

50

5


Drop - DONE

5.2.2 Modifying a RegistrationOnce a registration has been established between a Producer and a Consumer, in some conditions, Consumers may have to modify an existing registration relationship either to be able to continue to use a Producer or alter certain properties of the registration. Here are some possible situations that may warrant such an operation:

(a) Changes to Consumer’s capabilities: For example, Consumer may now be capable of supporting additional window states or modes. We shall discuss about window states and modes in the Section 6.

(b) Changes to registration properties: Producer requires a different set of registration properties than were previously used at the time of registration. In this case, the Consnumer may be required to supply the current registration properties to be able to continue to use the Producer.

Consider the following scenario.

P Inc now requires an email address of the Consumer to be supplied for each Consumer’s registration. C Inc sends a modifyRegistration request to P Inc supplying the email address along with the previously supplied registration properties.

Scenario 3: Modify RegistrationAt this point, P Inc has the following options:

(a) P Inc may return InvalidRegistration faults till the new property (email address) has been received.

(b) Or, inform C Inc (out of band) that a new property is required.

In the former case, C Inc will have to send getServiceDescription() request (without the registrationContext) to discover the current set of registration properties. Upon discovering the new registration property, C Inc sends the following modifyRegistration() request to P Inc.

<urn:modifyRegistration xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:registrationData> <urn:consumerName>C Inc</urn:consumerName> <urn:consumerAgent>C Inc Portal.1.0</urn:consumerAgent> <urn:methodGetSupported>false</urn:methodGetSupported> <urn:registrationProperties xml:lang="en" name="dunsNum"> <urn:stringValue>CIncDuncNumber</urn:stringValue> </urn:registrationProperties> <urn:registrationProperties xml:lang="en" name="serviceId"> <urn:stringValue>CIncServiceID</urn:stringValue> </urn:registrationProperties> <urn:registrationProperties xml:lang="en" name="email"> <urn:stringValue>[email protected]</urn:stringValue> </urn:registrationProperties> </urn:registrationData>


5

10

15

20

25

30

35

40

45

5


Ex: There is a new property required by the producer. Consumer calls modifyRegistration to supply the new property. - DONE

</urn:modifyRegistration>

Message 8: Request to Modify Registration with an Additional Registration Property

This request is similar to the registration request in Message 4: Registration Request except for a new value for a registration property.

P Inc validates the new values for registration properties, performs registration, and responds with the following message:

<urn:modifyRegistrationResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"/>

Message 9: Modify Registration Response

The response simply indicates that the request for modification of registration has been accepted.

If the Producer is not capable of managing persistent storage of the registration data, the Producer may return the updated registration state as registrationState in the modifyRegistrationResponse.

After modifying a registration relationship, C Inc can use the registrationHandle as it has now been reregistered with P Inc.

P Inc and C Inc decide to terminate the registration relationship as C Inc no longer wants to utilize P Inc’s portlets.

Scenario 4: Deregistration

5.2.3 Terminating a RegistrationRegistration relationships are not permanent. Either the Consumer or the Producer may terminate a registration relationship. Here are some scenarios that could prompt for a termination:

(a) Consumer decides not to aggregate portlets from a Producer. To notify that the Producer may no longer have to manage any portlet customizations and other persistent state created during the course of registration, the Consumer may send a request to the Producer to terminate the registration

(b) Producer decides to not offer portlets to a given Consumer. Producer may unilaterally terminate the registration, or notify (out of band) the Consumer that it will no longer offer any portlets to the Consumer.

(c) Consumer wants to recreate registration due to some changes in Consumer’s environment.

In cases (a) and (c) above, the Consumer can send a deregister() request to the Producer to terminate the current registration relationship. Note that, Consumer is not required to deregister always. But by formally deregistering, Consumer lets the Producer cleanup any persistent data maintained for that Consumer.

Consider that C Inc now wants to terminate its registration with P Inc. In order to to do so, C Inc sends a deregister() request with its registrationHandle to P Inc as shown below.


5

10

15

20

25

30

35

40

5

<urn:deregister xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle></urn:deregister>

Message 10: Deregister RequestP Inc then deregisters the consumer and may clean up any resources/state created (including any cloned portlets) for C Inc, and returns the following response.

<urn:deregisterResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"/>

Message 11: Deregister Response

After this step, C Inc can no longer use the registrationHandle for its requests to P Inc.

Terminating a registration has some consequences for both the Producer and the Consumer:(a) Consumer can delete any Producer-specific persistent state created.(b) Producer can also delete any Consumer-specific persistent state created.(c) Consumer can register again with the Producer, but should not refer to any cloned portlets

created during a terminated registration.(d) Producer should not serve portlets created during a terminated registration to other

Consumers.

Figure 2 shows possible interactions between C Inc and P Inc and the registration life cycle.


5

10

15

20

5


Be specific about portlet handle. Only applies to consumer created portlets. Need to also clarify CCP and POP somewhere in the spec.


Comments on producer initiated termination? - DONE


Motivate why a producer and/or consumer terminate a registration. What are the implications of a producer terminating a registration. - DONE

Figure 2: Registration Impact on Consumer-Producer Interactions

5.3 FaultsA consumer invoking operations on the registration interface must be prepared to handle the following faults:

(a) MissingParameters: A Producer throws this fault when certain expected data is missing in a given request. For example, in our scenario, P Inc sends this fault when C Inc sends a registration request without the service ID or the DUNS number.

(b) InvalidRegistration: A producer throws this fault when the registration data context supplied by the consumer is not valid. In the scenarios discussed above, P Inc sends this fault when C Inc invokes P Inc without modifying the registration relationship after entering into a revised service agreement. P Inc also sends this fault if C Inc sends the registrationHandle after deregistration.

(c) OperationFailed: A producer throws this fault when it fails to process any operation.

[Recommendations here]


5

10

15

5

, 01/03/-1,

Delete?

6 Markup Interface6.1 DescriptionIn order for a consumer to produce a viewable display of aggregated portlets offered by a producer, the consumer must first obtain the display information, the markup file or markup fragment, formatted in a desired markup language such as HTML or XHTML for a portlet from the producer. This pass-through of portlets offered by the producer with little or no change, until the user interacts with the features of the portlet is one of the primary benefits of using WSRP. The Markup Interface is required.

6.2 Purposes ServedThe getMarkup() operation of the Markup Interface serves the purpose of providing the portlet’s display instructions and current values for the portlet’s properties. This constitutes the current state of the portlet requested. The first getMarkup() operation that invokes an instance of a portlet from a producer also constitutes the initiation of the session which will be represented by the sessionID provided by the Producer in the getMarkupResponse. All portlet producers are required to support this operation. The option of using the navigationalState field to store the URL and reduce the overhead of regular page refresh tasks and to allow User bookmarking is carried in the MarkupParams structure in getMarkup() and peformBlockingInteraction()to propagate the state to the User’s browser as an optimization for handling persistent state. [See Section 6.3.1 and Section 6.3.2 of the WRSP 1.0 Specification for more details.]The performBlockingInteraction() operation of the Markup Interface serves the purpose of changing the portlet’s display instructions and/or current values for the portlet’s properties. This introduces the concept of changeable or transient state in addition to persistent states. Unlike a JSP or ASP web page, where obtaining the page resulting from an interaction such as clicking a submit button can be performed in a single operation, a portlet must be able to co-exist on the same page with other portlets possibly from the same Producer, or from different producers. This entails significant consequences for managing interactivity when a Producer wants to have shared state with other portlets being aggregated on the same page, such as when a Producer provides a common back-end database for those portlets. This consideratipn prompted WSRP’s two-step process whereby the interaction and any shared state with other portlets from the same producer on the same aggregated page takes precedence. Thus, performBlockingInteraction() is invoked and returned, before the Consumer can invoke getMarkup() for other portlets from that producer on the aggregated page once the interaction has been initiated. This allows Producer-mediated sharing to proceed safely (provided it happens in a synchronous manner)


5

10

15

20

25

30

35

5


Also introduce state management issues pertaining to the markup interface. Get into state management - session vs nav state. Also persistent state. Then to implicit cloning. Drive motivation for different kinds of state. Why portlets are designed to have customization state


Better to have a separate (sub) section on state management. Also talk about persistent state and forward reference to portlet management interface.


Also discuss why performBlockingInteraction is blocking. For state management, aggregation into pages, pushing state to browser etc.


Motivate the reader about interactions. Interactions require state changes. Motivate why there are two operations - getMarkup and performBlockingInteractionResponse. Why this is a single call in servlet /JSP?ASP programming models and why we need a two step process. Also mention bookmarkability. Why two calls, and the advantages to having. May mention why this is common in portlet programming.

This constitutes a new current state of the portlet requested. During the operation, the Consumer must not begin generation of the aggregated page containing the portlet nor gather markup for other portlets on that page. This ‘blocking’ allows Producer-mediated sharing with other portlets to proceed safely before any subsequent getMarkup() operations are allowed.

This operation creates a new value for navigationalState which the Consumer must specifically allow through the portletStateChange field value and must also supply to the Producer for any new invocations of getMarkup() or performBlockingInteraction() and must also change when propagated to the User’s browser.

6.3 State ManagementThe and performBlockingInteraction() operations of the Markup Interface are provided with the means for carrying persistent state and for changing state for the portlets delivered to the User. Recognizing that there are several common scenarios for Portlets with varying needs regarding statefulness, WSRP 1.0 provides a basic session ID mechanism and an optional navigational state mechanism for handling these in the Markup Interface. These scenarios and methods are detailed in Section 6.7 of the WSRP 1.0 Specification. Some of the underlying concepts within the InteractionParams Structure, specifically in the portletStateChange field for cloneBeforeWrite” introduces cloning portlets for optimization purposes which is more thoroughly developed in the Portlet Management Interface.However, it is important to remember that portlets have been designed to have interactive elements which necessitate having the means to manage statefulness and to customize and coordinate portletStateChange between Producer and Consumer to better serve the User.

6.4 Message FormatFollowing our example, a consumer, C Inc. sends the following SOAP message with the request document in the body of the message to the producer, P Inc. This message contains:

(a) RegistrationContext carries the registrationHandle which the Consumer uses to identify itself to the Producer.It may also include a base64Binary for registrationState and an array of any extensions the Producer provides.

(b) PortletContext carries the portletHandle which the Consumer uses to identify the portlet to the Producer. It may also include a base64Binary for portletState and an array of any extensions the Producers provides.

(c) RuntimeContext carries the userAuthetication the Consumer uses to identify the authentication that was done to authenticate the user. It may also include a portletInstanceKey, namespace prefix, templates, sessionID, and an array of any extensions the Producer provides.

(d) UserContext carries the userContextKey the Consumer uses to uniquely identify the UserContext. It may also include userCategories, a profile and any extensions the Producer provides.

(e) MarkupParams carries the boolean value for secureClientCommunication, an array for locales, an array for mimeTypes and the mode and window state. It may also include clientData, an array for navigationalState, an array for markupCharacterSets, a validateTag, an array for validNewModes, an array for validNewWindowStates and an array of any extensions the Producer provides.


5

10

15

20

25

30

35

40

45

5


Need to clean up messages.


Motivate and clarify different fields in messages.


We can skip templates from messages. Just build the motivation.

Note the following from this request:(a) RegistrationContext: The registrationHandle is CIncRegnHandle.(b) PortletContext: The portletHandle is portfolioManager.(c) RuntimeContext: The userAuthentication is wsrp:none. (d) UserContext: The declaration <urn:userContext xsi:nil=”true” …> means there is no

userContextKey or userCategories, but these data structures are still valid.(e) MarkupParams: the Boolean for secureClientCommunications is false, the locales is en,

the mimeTypes is text/html, the mode is wsrp:view, the windowState is wsrp:normal and the markupCharacterSet is UTF-8.

<urn:getMarkup xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:runtimeContext> <urn:userAuthentication>wsrp:none</urn:userAuthentication> </urn:runtimeContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:markupParams> <urn:secureClientCommunication>false</urn:secureClientCommunication> <urn:locales>en</urn:locales> <urn:mimeTypes>text/html</urn:mimeTypes> <urn:mode>wsrp:view</urn:mode> <urn:windowState>wsrp:normal</urn:windowState> <urn:markupCharacterSets>UTF-8</urn:markupCharacterSets> </urn:markupParams></urn:getMarkup>

Message 12 getMarkup Request

This is a basic form of a getMarkup Request that a consumer could send to a producer. Upon validating the registrationHandle, the producer may now send a getMarkupResponse that includes:

(a) MarkupContext which contains the markup for the portlet. (b) SessionContext with a sessionID, a value for expires and an array of any extensions the

Producer provides.(c) Extensions from namespaces other than WSRP.

Note in our example, the producer, P Inc. issues a response requires:(a) Username and password form inputs.(b) A preferredTitle Manage Your Portfolios which should be honored.(c) A sessionID 123456 which must be used.


5

10

15

20

25

30

35

40

45

5


Message 12 is not valid. Need to make sure all messages are valid.

<urn:getMarkupResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:markupContext> <urn:mimeType>text/html</urn:mimeType> <urn:markupString><![CDATA[<form method="post" action="wsrp_rewrite?wsrp-urlType=blockingAction&wsrp-secureURL=false&wsrp-interactionState= goNext%3Dlogin/wsrp_rewrite"> <table border="0" width="100%"> <tr> <td>Username:</td><td><input name="primerRemote1_name"></td> </tr> <tr> <td>Password:</td> <td><input name="primerRemote1_password"></td> </tr> <tr> <td><input type="submit" value="Login"></td> </tr> </table> </form>

<a href="wsrp_rewrite?wsrp-urlType=render&wsrp-secureURL=false&wsrp-navigationalState=primerRemote1_goNext%3Dforgot/wsrp_rewrite">Forgot password?</a>]]></urn:markupString> <urn:locale>en</urn:locale> <urn:preferredTitle>Manage Your Portfolios</urn:preferredTitle> </urn:markupContext> <urn:sessionContext> <urn:sessionID>123456</urn:sessionID> <urn:expires>3600</urn:expires> </urn:sessionContext></urn:getMarkupResponse>

Message 13: getMarkup Response


5

10

15

20

25

30

5

The following markup fragment shows the getMarkupResponse rewritten for aggregation by the Consumer, C Inc. (Need help on motivation for consumer rewriting v. producer writing, makes somewhat more sense if the example is adding a stock symbol, after authentication has already been done as part of the performBlockingInteraction example, rather than as part of the first getMarkup example. Consumer then knows the User’s preferences for selection mechanism for adding a new symbol (at start, at end , in alphabetical order, by category, etc.)C Inc. rewrites the markup fragment to fit into its design choices, such as renaming the form’s input name from <input name="primerRemote1_name"> to <input name="pfm_name">.

The reason for such a choice might be that C Inc. wants to mediate such interactions to keep transient state content, such as the value entered for username separate from persistent state content. A portlet that was simply a list of stock symbols offered by the Portoflio Manager to potential clients could be an example of such unchanging static content that requires no interactions or allows none until a User enters into a formal, authenticated relationship with P Inc. That might also be the case after this authentication has proceeded if the portlet contains no further interaction options for the User. In that case, C Inc. might push that resulting navigationalState out to the User’s browser for easy page refreshing or User bookmarking.

<form action="http://cinc.com/portfolio? wsrp-interactionState= goNext%3Dlogin&wsrp-urlType=blockingAction" method="post"> <table width="100%" border="0"> <tr> <td>Username:</td> <td><input name="pfm_name"></input></td> </tr> <tr> <td>Password:</td> <td><input name="pfm_password"></input></td> </tr> <tr> <td><input value="Login" type="submit"></input></td>


5

10

15

20

25

30

5


Motivate consumer rewriting vs producer writing of URLs. Assume consumer rewriting. Describe conceptually. Benefits of either approach. Simplicity vs complexity. Static content (a requirement) markup is independent of the consumer.

</tr> </table></form>

<a href="http://cinc.com/portfoilo? wsrp-navigationalState=goNext%3Dforgot&wsrp-urlType=render">Forgot password?</a>

Rewritten Form Markup

6.5 Interaction OperationsThe Markup Interface is used in two operational processes that change the state of the portlet such as authentication in the example above or if, for instance, a new stock symbol is added to the collection of stocks in the User’s Portfolio Manager Portlet:The performBlockingInteraction() operation: This operation adds InteractionParams to the group of RegistrationContext, PortletContext, RuntimeContext, UserContext and MarkupParams of the getMarkup() operation data structures and requires, as previously explained that other operations for the page in which the affected portlet appears be suspended until it is finished.

(d) InteractionParams: the portletStateChange flag which can have a value of “readWrite”, “cloneBeforeWrite” or “readOnly” which the Consumer sets to indicate if a state change is acceptable, an interactionState string if any, an array of any formParameters, an array of any uploadContexts and an array of any extensions.

Updating Persistent Portlet State: The Consumer indicates whether or not it is safe for the Portlet to modify its persistent state by setting the portletStateChange field in the InteractionParams structure. While such changes usually occur during a performBlockingInteraction() operation for a specific portlet, the value of this field in other portlets from the same Producer allows those other portlets to be updated during such operations. (This is detailed in Section 6.3.2 of WSRP 1.0.)

The following messages shows a performBlockingInteraction request message as it would be generated if the form from the Rewritten Form Markup is submitted to the Consumer providing the portlet to the end-user and passed on to the Producer. This is followed by the performBlockingInteraction response message .

<urn:performBlockingInteraction xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:runtimeContext> <urn:userAuthentication>wsrp:none</urn:userAuthentication> <urn:sessionID>123456</urn:sessionID> </urn:runtimeContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>


5

10

15

20

25

30

35

40

45

5


Not clear. What is the state of the portlet?

<urn:markupParams> <urn:secureClientCommunication>false</urn:secureClientCommunication> <urn:locales>en</urn:locales> <urn:mimeTypes>text/html</urn:mimeTypes> <urn:mode>wsrp:view</urn:mode> <urn:windowState>wsrp:normal</urn:windowState> <urn:markupCharacterSets>UTF-8</urn:markupCharacterSets> </urn:markupParams> <urn:interactionParams> <urn:portletStateChange>readWrite</urn:portletStateChange> <urn:interactionState>goNext=login</urn:interactionState> <urn:formParameters name="pfm_name"> <urn:value>password</urn:value> </urn:formParameters> </urn:interactionParams></urn:performBlockingInteraction>

Message 14: PerformBlockingInteraction Request


5

10

15

5

This request is answered with the following message.

<urn:updateResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:navigationalState>goNext=main</urn:navigationalState></urn:updateResponse>

Message 16: PerformBlockingInteractionResponse

For the purpose of brevity, let’s assume that the markupString is received, rewritten if necessary and presented to the end-user . Only then is it allowed to send another getMarkup request to the Producer.The following diagrams represent these kinds of interactions.

6.5.1 Using InitCookieManaging persistent state includes managing cookies. While the producer is responsible for managing its own environment, it is useful in some instances, such as load balancing, for the Consumer to assist in initializing cookies. (The requiresInitCookie field only occurs in the specification in Section 6.4 The initCookie() Operation, so it is assumed that it is an extension of the RegistrationContext, so I think we need to discuss how much to put into this section in regard to session v. persistent cookies.)


5

10

15

20

5


Talk about different kinds of cookies. This concept is somewhat confusing.


Inline the diagrams with the messages. Can not collect form data from render URLs. Spell-check Separate initCookie diagram for cookies and sessions

For example, before the getMarkup for Message 14 the following InitCookie could have been sent to the Producer.

<<urn:initCookie xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext></urn:initCookie>

Message 17: InitCookie Request

<urn:initCookieResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"/>

Message 18: InitCookie Response

The following diagram shows updating persistent portal state, using InitCookie()

6.5.2 Releasing SessionsAs with cookies, and as shown above, it can be useful for the Consumer to inform the Producer that it will no longer be using a set of sessions by invoking releaseSessions(). This requires specifying the registrationContext and sessionID(s). The Consumer must not include any of supplied sessionID(s) on subsequent invocations.

6.6 M odes and Window StatesThe Markup Interface is used in five “Modes:” Modes refer to the specific ways in which the Consumer manages the interaction with the End-User. Portlets specify what Modes are supported in PortletDescription.The Consumer indicates the Mode to the portlet during getMarkup() and performBlockingInteraction() invocations using the MarkupParams data structure. Modes determine the administrative state of the portlet, i.e. how it is being used such as getting help using the portlet or modifying the display of the portlet , while Window States determine the relationship of the portlet to the overall page in terms of size or dominance.


5

10

15

20

25

30

5


Need to motivate the notion of states and modes. How do consumers/producers may interpret different modes and states. Ex, minimized, maximized etc.


View and normal are required. Mention why?

“wsrp:view” Mode: This mode is expected to render markup reflecting the current state of the Portlet. This includes any interactions, personalizations and all forms of state available to the user. This mode is required since it is the expected default mode.. “wsrp:edit” Mode: This mode is expected to allow user to customize portlet behavior(s). Such state changes are expected to be persistent per portlet per user. This mode is optional.“wsrp:help” Mode: This mode is expected to allow help screens to explain Portlet usage. This mode is optional.“wsrp:preview” Mode: This mode is expected to provide a rendering of its standard “wsrp:view” mode content, as a visual sample of how this Portlet will appear on the End-User’s page with the current configuration. This mode is optional.“wsrp:custom” Mode: The extensible RegistrationData structure provides a field for Consumers to declare additional custom modes. In addition, the extensible PortletDescription structure provides a field for Portlets to declare what modes they understand. The Markup Interface is used in four “Window States:” Window state is an indicator or hint of the amount of page space that will be assigned to the Portlet.“wsrp:normal” Window State: This state indicates the Portlet is likely sharing the aggregated page with other Portlets. This state may indicate device-specific display constraints. This state is required, as with the view mode, since this is the expected default window state.“wsrp:minimized” Window State: This state indicates that no visible state should be rendered, but non-visible data such as JavaScript or hidden forms is allowed and the getMarkup() operation may be optionally invoked, This state is optional.“wsrp:maximized” Window State: This state indicates that the Portlet is the only or largest Portlet on a page.This state is optional. “wsrp:solo” Window State:This state indicates that the Portlet is the only Portlet on a page. This state is optional.Custom Window States: The extensible RegistrationData structure provides a field for Consumers to declare additional custom window states. In addition, the extensible PortletDescription structure contains a field for Portlets to declare what window states they understand.

6.7 User Categories

7 Markup Interface7.1 DescriptionIn order for a consumer to produce a viewable display of aggregated portlets offered by a producer, the consumer must first obtain the display information, the markup file or markup fragment, formatted in a desired markup language such as HTML or XHTML for a portlet from the producer. This pass-through of portlets offered by the producer with little or no change, until the user interacts with the features of the portlet is one of the primary benefits of using WSRP. The Markup Interface is required.Purposes ServedThe getMarkup() operation of the Markup Interface serves the purpose of providing the portlet’s display instructions and current values for the portlet’s properties. This constitutes the current state of the portlet requested. The first getMarkup() operation that invokes an instance of a portlet from a producer also constitutes the initiation of the session which will be represented by the sessionID provided by the Producer in the getMarkupResponse. All portlet producers are required to support this operation, which includes the following:


5

10

15

20

25

30

35

40

45

5


Rich: ?


Also introduce state management issues pertaining to the markup interface. Get into state management - session vs nav state. Also persistent state. Then to implicit cloning. Drive motivation for different kinds of state. Why portlets are designed to have customization state


Better to have a separate (sub) section on state management. Also talk about persistent state and forward reference to portlet management interface.


Also discuss why performBlockingInteraction is blocking. For state management, aggregation into pages, pushing state to browser etc.


Rich: ?


Motivate the reader about interactions. Interactions require state changes. Motivate why there are two operations - getMarkup and performBlockingInteractionResponse. Why this is a single call in servlet /JSP?ASP programming models and why we need a two step process. Also mention bookmarkability. Why two calls, and the advantages to having. May mention why this is common in portlet programming.


getMarkup is optional for this state.

RegistrationContext : carries the registrationHandle which the Consumer uses to identify itself to the Producer.It may also include a base64Binary for registrationState and an array of any extensions the Producer provides.

(a) PortletContext: carries the portletHandle which the Consumer uses to identify the portlet to the Producer. It may also include a base64Binary for portletState and an array of any extensions the Producers provides.

(a) RuntimeContext : carries the userAuthetication which specifies how the Consumer uses to identify the authentication authenticated the userthat was done to authenticate the user. It may also include a portletInstanceKey, namespace prefix, templates, sessionID, and an array of any extensions the Producer provides.

(a) UserContext : carries the userContextKey the Consumer uses to uniquely identify the UserContext. It may also include userCategories, a profile and any extensions the Producer provides.

(a) MarkupParams : carries the a boolean value for secureClientCommunication, an array for locales, an array for mimeTypes and the mode and window state. It may also include clientData, an array for navigationalState, an array for markupCharacterSets, a validateTag, an array for validNewModes, an array for validNewWindowStates and an array of any extensions the Producer provides.

(a) The performBlockingInteraction() operation of the Markup Interface serves the purpose of changing the portlet’s display instructions and/or current values for the portlet’s properties. This constitutes a new current state of the portlet requested. During the operation, the Consumer must not begin generation of the aggregated page containing the portlet nor gather markup for other portlets on that page. This allows any Producer-mediated sharing with other portlets to proceed safely before any subsequent getMarkup() operations are allowed. Because there are significant consequences involved with this operation, it is suggested that the WSRP Specification Section 6.3.1 be read carefully.


5

10

15

20

25

5


Rich: “current state”.


Subbu: Do we want to mention extensions at this stage?

Message FormatFor example, a consumer sends a SOAP message with the following request document in the body of the message to the producer:

<urn:getMarkup xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:runtimeContext> <urn:userAuthentication>wsrp:none</urn:userAuthentication> </urn:runtimeContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:markupParams> <urn:secureClientCommunication>false</urn:secureClientCommunication> <urn:locales>en</urn:locales> <urn:mimeTypes>text/html</urn:mimeTypes> <urn:mode>wsrp:view</urn:mode> <urn:windowState>wsrp:normal</urn:windowState> <urn:markupCharacterSets>UTF-8</urn:markupCharacterSets> </urn:markupParams></urn:getMarkup<urn:getMarkup xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/><portletContext> <portletHandle>portfolioManager</portletHandle></portletContext><runtimeContext> <userAuthentication>none</userAuthentication><userContext> <userContextKey>54321</userContextKey></userContext><markupParams> <secureClientCommunication>false</secureClientCommunication> <locales>en</locales> <mimeTypes>text/html</mimeTypes> <mode>wsrp:view</mode> <windowState>wsrp:normal</windowState></markupParams></urn:getMarkup>Message 15: Get Markup RequestMessage 16 Markup Request (without registration)

This is a basic form of a getMarkup request that a consumer could send to a producer. This request contains RegistrationContext, PortletContext, RuntimeContext, UserContext and MarkupParams in a minimal configuration. To this request, the producer sends a getMarkupResponse document that includes MarkupContext which contains the markup for the portlet and


5

10

15

20

25

30

35

40

45

50

5


Message 12 is not valid. Need to make sure all messages are valid. Subbu: Replaced with a valid message Also, I included the registrationContext we introduced in the previous section. So, I don’t think we need to include two sets of messages anymore.


urn: prefixes needed Subbu: Done.


Motivate and clarify different fields in messages.


We can skip templates from messages. Just build the motivation.

may include SessionContext with a sessionID, a value for expires and an array of any extensions the Producer provides.This request contains RegistrationContext, PortletContext, RuntimeContext, UserContext and MarkupParams in a minimal configuration.

Here is a sample response from a producer with a different set of capabilities and portlets

<urn:getMarkupResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:requiresRegistration>true</urn:requiresRegistration> <urn:requiresInitCookie>perGroup</urn:requiresInitCookie> <urn:locales>en</urn:locales> <urn:locales>en-US</urn:locales></urn:getMarkupResponse>Message 17: Get Markup Response – To be deletedMessage 13: Markup Response (without registration)The first point to notice is that this producer requires registration. The service description may not provide much information to the consumer. Such a producer may provide a more useful description based on consumer registration. If registration requires additional data, the producer may provide registration properties that the consumer must supply values for.

The consumer may then register with the producer, and resend the getMarkup request with the registrationHandle returned by the producer upon registration.Here is a sample getMarkup request with full registration and service description information for the portlet being requested. <getMarkupxmlns="urn:oasis:names:tc:wsrp:v1:types"> <registrationContext>

<registrationHandle>uri:Portlet6test.LZAFuOV9iM4EVeKVYnd</registrationHandle> </registrationContext> <portletContext> <portletHandle>WSRP_Portlets:Portlet6</portletHandle> </portletContext> <runtimeContext> <userAuthentication>wsrp:password</userAuthentication>

<portletInstanceKey>qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d</portletInstanceKey> <namespacePrefix>portlet0</namespacePrefix> <templates> <defaultTemplate>http://knowth/Portlet6/Page.aspx?vid=qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d&ut={wsrp-urlType}&is={wsrp-interactionState}&ns={wsrp-navigationalState}&m={wsrp-mode}&ws={wsrp-windowState}</defaultTemplate> <resourceTemplate>http://knowth/Portlet6/Page.aspx?vid=qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d&wsrp-url={wsrp-url}&rewrite={wsrp-requiresRewrite}</resourceTemplate>


5

10

15

20

25

30

35

40

45

50

55

5


Message 13 is incorrect. It should be throwing a fault with the given case. Text below this message is incorrect. Needs to be cleaned up.


Explain?

<secureDefaultTemplate>https://knowth/Portlet6/Page.aspx?vid=qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d&ut={wsrp-urlType}&is={wsrp-interactionState}&ns={wsrp-navigationalState}&m={wsrp-mode}&ws={wsrp-windowState}</secureDefaultTemplate> <secureResourceTemplate>https://knowth/Portlet6/Page..aspx?vid=qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d&wsrp-url={wsrp-url}&rewrite={wsrp-requiresRewrite}</secureResourceTemplate> </templates> </runtimeContext> <userContext> <userContextKey>12345</userContextKey> <profile> <name> <given>Joe</given> <family>Primer</family> </name> </profile> </userContext> <markupParams> <secureClientCommunication>false</secureClientCommunication> <locales>en</locales> <mimeTypes>text/html</mimeTypes> <mode>wsrp:view</mode> <windowState>wsrp:normal</windowState> <clientData> <userAgent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; Q312461; (R1 1.1)</userAgent> </clientData> <markupCharacterSets>UTF-8</markupCharacterSets> <markupCharacterSets>UTF-16</markupCharacterSets> </markupParams></getMarkup>Message 14: getMarkup Request (with registration)Note the following from this request:RegistrationContext: The registrationHandle is uri:Portlet6test.LZAFuOV9iM4EVeKVYndPortletContext: The portletHandle is WSRP_Portlets:Portlet6RuntimeContext: The userAuthentication is password, the portletInstanceKey is qGBYRXJVOtTQ6SMZtBWlapK4ihc%3d, the namespacePrefix is portlet0 and the templates with their URLs are defaultTemplate , resourceTemplate secureDefaultTemplate and secureResourceTemplate d. UserContext: The userContextKey is 12345., the userCategories are not used and the profile contains a name with Joe as the given value and Primer as the family value.e. MarkupParams: the Boolean for secureClientCommunications is false,


5

10

15

20

25

30

35

40

45

50

55

5


Need to clean up messages. Subbu: Is this required, since the previous message already includes registrationContexte Your Portfolios"ets of messagtexted during a terminated registration to Consumers with aing a differentr cleanup any pers

the locales is en, the mimeTypes is text/html, the mode is wsrp:view and the windowState is wsrp:normal.

Upon validating the registrationHandle, the producer may now send a getMarkupResponse that includes markupContext containing the actual markup for the portlet

<urn:getMarkupResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:markupContext> <urn:mimeType>text/html</urn:mimeType> <urn:markupString><![CDATA[<form method="post" action="wsrp_rewrite?wsrp-urlType=blockingAction&wsrp-secureURL=false&wsrp-interactionState= goNext%3Dlogin/wsrp_rewrite"> <table border="0" width="100%"> <tr> <td>Username:</td><td><input name="primerRemote1_name"></td> </tr> <tr> <td>Password:</td> <td><input name="primerRemote1_password"></td> </tr> <tr> <td><input type="submit" value="Login"></td> </tr> </table> </form>

<a href="wsrp_rewrite?wsrp-urlType=render&wsrp-secureURL=false&wsrp-navigationalState=primerRemote1_goNext%3Dforgot/wsrp_rewrite">Forgot password?</a>]]></urn:markupString> <urn:locale>en</urn:locale> <urn:preferredTitle>Manage Your Portfolios</urn:preferredTitle> </urn:markupContext> <urn:sessionContext> <urn:sessionID>123456</urn:sessionID> <urn:expires>3600</urn:expires> </urn:sessionContext></urn:getMarkupResponse><getMarkupResponse xmlns="urn:oasis:names:tc:wsrp:v1:types"> <markupContext> <mimeType>text/html</mimeType> <markupString> … </markupString> <locale>en</locale> <preferredTitle>Cascading Style Sheet Example Portlet</preferredTitle> </markupContext> <sessionContext> <sessionID>sid.e2++DxoNsrhmQ8l0fWpMg19s8DM=</sessionID> <expires>-1</expires> </sessionContext> </getMarkupResponse>Message 18: Markup Response (with registration)


5

10

15

20

25

30

35

40

45

50

55

5


Session context will only appear if a new session has been initiated. Clarify this point.


Use earlier value

When compared to the MarkupResponse shown in Message 13, this response shows certain additional requirements from the producer for the consumer:Since this producer requires registration, the consumer is required to supply the registrationHandle with all its interactions with the producer.The producer has indicated a preferredTitle “Cascading Style Sheet Example PortletManage Your Portfolios” which should be honored.The producer has supplied a sessionID sid.e2++DxoNsrhmQ8l0fWpMg19s8DM=123456 which must be used.

For the sake of brevity, let’s assume that the following markup fragment represents the markupString shown as ellipsis in Message 16 after it has been processed. Depending on how it is aggregated by the Consumer some amount of rewriting is necessary to make it ready for inclusion in the page where it will appear.

<form action="http://cinc.com/portfolio? wsrp-interactionState= goNext%3Dlogin&wsrp-urlType=blockingAction" method="post"> <table width="100%" border="0"> <tr> <td>Username:</td> <td><input name="pfm_name"></input></td> </tr> <tr> <td>Password:</td> <td><input name="pfm_password"></input></td> </tr> <tr> <td><input value="Login" type="submit"></input></td> </tr> </table></form>

<a href="http://cinc.com/portfoilo? wsrp-navigationalState=goNext%3Dforgot&wsrp-urlType=render">Forgot password?</a>

<div align="right"> <img src="http://ada:7001/qaConsumer/resource?_windowLabel=primerRemote1&wsrp-url=http%3A%2F%2Flocalhost%3A7001%2FjavaPortletProducer%2Fprimer%2Foasis_logo.gif&wsrp-requiresRewrite=true&wsrp-urlType=resource"> </img> </div> <form id="primerRemote1_form" action=http://ada:7001/qaConsumer/primer/Primer.portal?_nfpb=true&_windowLabel=primerRemote1&wsrp-navigationalState=primerRemote1_goNext%3Dlogin&wsrp-urlType=blockingAction method="post"> <table width="100%"border="0"> <tr> <td>Username:</td> <td><input name="primerRemote1_name"></input></td> </tr> <tr>


5

10

15

20

25

30

35

40

45

50

55

5


Motivate consumer rewriting vs producer writing of URLs. Assume consumer rewriting. Describe conceptually. Benefits of either approach. Simplicity vs complexity. Static content (a requirement) markup is independent of the consumer.

http://ada:7001/qaConsumer/primer/Primer.portal?_nfpb=true&_windowLabel=primerRemote1&wsrp-navigationalState=primerRemote1_goNext%3Dlogin&wsrp-urlType=blockingAction



<td>Password:</td> <td><input name="primerRemote1_password"></input> </td> </tr> <tr> <td><input value="Login" type="submit"></input> </td> </tr> </table> </form> <a href="http://ada:7001/qaConsumer/primer/Primer.portal?_nfpb=true&_windowLabel=primerRemote1&wsrp-navigationalState=primerRemote1_goNext%3Dforgot&wsrp-urlType=render">Forgot password?</a>

Rewritten Form Markup


5

10

15

5

7.2 Interaction OperationsThe Markup Interface is used in two operational processes that change the state of the portlet:The performBlockingInteraction() operation: This operation adds InteractionParams to the group of RegistrationContext, PortletContext, RuntimeContext, UserContext and MarkupParams data structures and requires that other operations for the page in which the affected portlet appears be suspended until it is finished. InteractionParams: the portletStateChange flag which can have a value of “readWrite”, “cloneBeforeWrite” or “readOnly” which the Consumer sets to

indicate if a state change is acceptable, an interactionState string if any, an array of any formParameters an array of any uploadContexts and an array of any extensions. Updating Persistent Portlet State: The Consumer indicates whether or not it is safe for the Portlet to modify its persistent state by setting the portletStateChange field in the InteractionParams structure. (This is detailed in Section 6.3.2 of WSRP 1.0.)

The following message shows a performBlockingInteraction request message as it would be generated if the form from the Rewritten Form Markup is submitted to the Consumer providing the portlet to the end-user.

<urn:performBlockingInteraction xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:runtimeContext> <urn:userAuthentication>wsrp:none</urn:userAuthentication> <urn:sessionID>123456</urn:sessionID> </urn:runtimeContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:markupParams> <urn:secureClientCommunication>false</urn:secureClientCommunication> <urn:locales>en</urn:locales> <urn:mimeTypes>text/html</urn:mimeTypes> <urn:mode>wsrp:view</urn:mode> <urn:windowState>wsrp:normal</urn:windowState> <urn:markupCharacterSets>UTF-8</urn:markupCharacterSets> </urn:markupParams> <urn:interactionParams> <urn:portletStateChange>readWrite</urn:portletStateChange> <urn:interactionState>goNext=login</urn:interactionState> <urn:formParameters name="pfm_name"> <urn:value>password</urn:value> </urn:formParameters> </urn:interactionParams></urn:performBlockingInteraction><urn:performBlockingInteraction xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext xsi:nil="true"


5

10

15

20

25

30

35

40

45

50

5


Not clear. What is the state of the portlet?

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:portletContext> <urn:portletHandle>primerPortlet</urn:portletHandle> </urn:portletContext> <urn:runtimeContext> <urn:userAuthentication>wsrp:none</urn:userAuthentication> <urn:portletInstanceKey>primerRemote1</urn:portletInstanceKey> <urn:sessionID>A0YlJwOcfB1bnYSoWE9MdScCjJ2worBCe0Ja8S</urn:sessionID> </urn:runtimeContext> <urn:userContext> <urn:userContextKey>anonymous</urn:userContextKey> </urn:userContext> <urn:markupParams> <urn:secureClientCommunication>false</urn:secureClientCommunication> <urn:locales>en-US</urn:locales> <urn:locales>en</urn:locales> <urn:mimeTypes>text/html</urn:mimeTypes> <urn:mimeTypes>text/xml</urn:mimeTypes> <urn:mimeTypes>application/xml</urn:mimeTypes> <urn:mimeTypes>application/xhtml+xml</urn:mimeTypes> <urn:mimeTypes>text/plain</urn:mimeTypes> <urn:mimeTypes>video/x-mng</urn:mimeTypes> <urn:mimeTypes>image/png</urn:mimeTypes> <urn:mimeTypes>image/jpeg</urn:mimeTypes> <urn:mimeTypes>image/gif</urn:mimeTypes> <urn:mimeTypes>*/*</urn:mimeTypes> <urn:mode>wsrp:view</urn:mode> <urn:windowState>wsrp:normal</urn:windowState> <urn:clientData> <urn:userAgent>Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040207 Firefox/0.8</urn:userAgent> </urn:clientData> <urn:markupCharacterSets>ISO-8859-1</urn:markupCharacterSets> <urn:markupCharacterSets>utf-8</urn:markupCharacterSets> <urn:markupCharacterSets>*</urn:markupCharacterSets> <urn:markupCharacterSets>UTF-16</urn:markupCharacterSets> </urn:markupParams> <urn:interactionParams> <urn:portletStateChange>readOnly</urn:portletStateChange> <urn:formParameters name="primerRemote1_password"> <urn:value>password</urn:value> </urn:formParameters> <urn:formParameters name="primerRemote1_name"> <urn:value>joedeveloper</urn:value> </urn:formParameters> </urn:interactionParams></urn:performBlockingInteraction>Message 19: PerformBlockingInteraction Request

<urn:updateResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types">

<urn:navigationalState>goNext=main</urn:navigationalState></urn:updateResponse><performBlockingInteractionResponse xmlns="urn:oasis:names:tc:wsrp:v1:types">


5

10

15

20

25

30

35

40

45

50

55

5

<updateResponse> <sessionContext> <sessionID>sid.e2++DxoNsrhmQ8l0fWpMg19s8DM=</sessionID> <expires>-1</expires> </sessionContext> <portletContext> <portletHandle>WSRP_Portlets:Portlet6</portletHandle> </portletContext> <markupContext> <mimeType>text/html</mimeType> <markupString> … </markupString> <locale>en</locale> </markupContext> <navigationalState /> </updateResponse></performBlockingInteractionResponse>Message 18: PerformBlockingInteractionResponse

Again, for the purpose of brevity, let’s assume that the markupString is received, rewritten if necessary and presented to the end-user . Only then is it allowed to send another getMarkup request to the Producer.


5

10

15

20

5


Since we are interested in concepts, and having MarkupContext in pbia response is an optimization, suggests to exclude the MarupContext from the response, but mention it as an optimization. Subbu: Done. Removed markupContext from this message.

The following diagrams represent these kinds of interactions.


5


Inline the diagrams with the messages. Can not collect form data from render URLs. Spell-check Separate initCookie diagram for cookies and sessions

Using InitCookieManaging persistent state includes managing cookies. While the producer is responsible for managing its own environment, it is useful in some instances, such as load balancing, for the Consumer to assist in initializing cookies.

For example, before the getMarkup for Message 14 the following InitCookie could have been sent to the Producer.

<urn:initCookie xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext></urn:initCookie><initCookie xmlns="urn:oasis:names:tc:wsrp:v1:types"> <registrationContext>

<registrationHandle>uri:Portlet6:test.LZAFuOV9iM4EVeKVYnd</registrationHandle></registrationContext></initCookie>Message 20: InitCookie Request

<urn:initCookieResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"/><initCookieResponse xmlns="urn:oasis:names:tc:wsrp:v1:types" />Message 19: InitCookie and InitCookieResponseResponse

The following diagram shows updating persistent portal state, using InitCookie()

Releasing Sessions


5

10

15

20

25

30

5


Talk about different kinds of cookies. This concept is somewhat confusing.

As with cookies, and as shown above, it can be useful for the Consumer to inform the Producer that it will no longer be using a set of sessions by invoking releaseSessions(). This requires specifying the registrationContext and sessionID(s). The Consumer must not include any of supplied sessionID(s) on subsequent invocations.

Modes and StatesThe Markup Interface is used in five “Modes:” Modes refer to the specific ways in which the Consumer manages the interaction with the End-User. Portlets specify what Modes are supported in PortletDescription.The Consumer indicates the Mode to the portlet during getMarkup() and performBlockingInteraction() invocations using the MarkupParams data structure. “wsrp:view” Mode: This mode is expected to render markup reflecting the current state of the Portlet. This includes any interactions, personalizations and all forms of state available to the user. This mode is required. “wsrp:edit” Mode: This mode is expected to allow user to customize portlet behavior(s). Such state changes are expected to be persistent per portlet per user. This mode is optional.“wsrp:help” Mode: This mode is expected to allow help screens to explain Portlet usage. This mode is optional.“wsrp:preview” Mode: This mode is expected to provide a rendering of its standard “wsrp:view” mode content, as a visual sample of how this Portlet will appear on the End-User’s page with the current configuration. This mode is optional.“wsrp:custom” Mode: The extensible RegistrationData structure provides a field for Consumers to declare additional custom modes. In addition, the extensible PortletDescription structure provides a field for Portlets to declare what modes they understand. The Markup Interface is used in four “Window States:” Window state is an indicator or hint of the amount of page space that will be assigned to the Portlet.“wsrp:normal” Window State: This state indicates the Portlet is likely sharing the aggregated page with other Portlets. This state may indicate device-specific display constraints. This state is required.“wsrp:minimized” Window State: This state indicates that no visible state should be rendered, but non-visible data such as JavaScript or hidden forms is allowed and the getMarkup() operation may be invoked. This state is optional.“wsrp:maximized” Window State: This state indicates that the Portlet is the only or largest Portlet on a page.This state is optional.


5

10

15

20

25

30

35

5


getMarkup is optional for this state.


Need to motivate the notion of states and modes. How do consumers/producers may interpret different modes and states. Ex, minimized, maximized etc.


View and normal are required. Mention why?

“wsrp:solo” Window State:This state indicates that the Portlet is the only Portlet on a page. This state is optional.Custom Window States: The extensible RegistrationData structure provides a field for Consumers to declare additional custom window states. In addition, the extensible PortletDescription structure contains a field for Portlets to declare what window states they understand.User CategoriesThis feature is entirely optional. The specification states: “A Producer’s ServiceDescription MAY declare support for user categories. A Consumer MAY map End-Users to the user categories a Producer declares…”User Category Assertions The reader should look at the Section 6.10.1 for a description of the available configurations of Producer and Consumer support for this set of features.

7.3 FaultsA consumer invoking the getMarkup operation must be prepared to handle the following faults: AccessDenied: InconsistentParameters:InvalidRegistration:MissingParameters:OperationFailed:InvalidUserCategory:InvalidHandle:InvalidCookie:InvalidSession:UnsupportedWindowState:UnsupportedLocale:UnsupportedMimeTypes:

8 Portlet Management InterfaceThe purpose of the portlet management interface is to let Consumers discover and customize properties associated with a portlet. This interface also allows a Consumer to clone a portlet, and destroy it when it is no longer in use.

Portlet properties are data associated with a portlet. By declaring properties for a portlet, the portlet allows customization of its behavior for each usage. An example of a portlet property is the list of stock symbols for the portfolioManager portlet. While this portlet encapsulates the functionality necessary to manage portfolios, the portlet may declare the list of the stock symbols as a property. However, since a Producer may offer the same portlet to several Consumers, and since each such Consumer may allow a number of users to use the same portlet, it is essential to be able to manage values of portlet properties for each distinct usage of the portlet.


5

10

15

20

25

30

35

40

5


This is for managing explicit lifecycle of persistent state of portlets.


This section is dominated by messages. Needs more flow with text


Questions on the sprinkling faults across the primer. Move to Section 9. Discuss operation-specific faults inline with messages.

, 01/03/-1,

Delete?


Questions on user categories. Mike suggests that "categories is an application description of category of a user" not related to security role of a user.

In typical web applications, it is common to provide a user interface to let users change values of such properties, and store values of those properties for the user persistently. This allows each user to customize the behavior of the application. However, when the same application is offered as a portlet via a Producer, such customization may be performed in two ways:

Each user of the portlet (via a Consumer) customizes the values of properties via the user interface provided by the portlet. For example, the portfolioManager portlet may offer a page with a form to let the users enter the list of stock symbols. When the user submits new values, the Producer or the portlet may implicitly clone the portlet (refer to XXX [Editorial Note: should refer to Rex’s markup section]). In this scenario, the Consumer does not directly participate in the customization process. The customization is implicit and occurs during a user interaction with the portlet.The Consumer offers a user interface to let users view the values of properties, and change their values. In our sample scenario, C Inc may offer a page to administer these properties. In this scenario, the user interacts with the Consumer, and not the portlet, for customization.

The portlet management interface is designed to address the second scenario. This interface specifies mechanisms using which a Consumer and a Producer will be able to create and manage multiple customizations of a portlet. This is an optional interface, and only producers offering portlet customization may implement this interface. This interface specifies the following operations.

getPortletDescription(): Get the description of a portlet.

getPortletPropertyDescription(): Get the description of properties (if any) of a portlet


5

10

15

20

5

getPortletProperties(): Get the properties (including their current values) of a portlet

setPortletProperties(): Set the values of properties of a portlet. This operation may implicitly clone a portlet.clonePortlet(): To explicitly clone a portlet, such that any properties associated with the cloned portlet may be modified without affecting the properties of the portlet that it is cloned fromdestroyPortlets(): To destroy portlets cloned explicitly or implicitly

8.1 Message Format

8.1.1 getPortletDescriptionC Inc provides a page for its users to view the description of the portfolioManager portlet.

C Inc sends a getPortletDescription() request to P Inc to obtain the description of the portfolioManager portlet.

C Inc then uses the returned description to create a page.

Scenario 5: Get Portlet DescriptionC Inc. sends the following message to obtain the description of the portfolioManager portlet.

<urn:getPortletDescription xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CincRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:desiredLocales>en</urn:desiredLocales></urn:getPortletDescription>

Message 20: Get Portlet Description Request

In response, P Inc sends the following message with the description of the portlet:

<urn:portletDescription xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:portletHandle>portfolioManager</urn:portletHandle> <urn:markupTypes> <urn:mimeType>text/html</urn:mimeType> <urn:modes>wsrp:view</urn:modes> <urn:windowStates>wsrp:normal</urn:windowStates> <urn:locales>en</urn:locales> </urn:markupTypes> <urn:description xml:lang="en"> <urn:value>Manages portfolios</urn:value>


5

10

15

20

25

30

35

40

45

5

</urn:description> <urn:title xml:lang="en"> <urn:value>Title</urn:value> </urn:title></urn:portletDescription>

Message 21: Get Portlet Description Response

Note that the portletDescription returned in this message is the same as the one returned by the getServiceDescription() operation of the service description interface shown in Message 7: Service Description Response after Registration.

In order to setup a page to administer the properties of the portfolioManager portlet, C Inc. invokes the getPortletPropertyDescription() operation. Using the descriptions and types of these properties, C Inc designs a page.

Scenario 6: Get Portlet Property Desription

C Inc sends the following request to obtain a description of all properties associated with the portfolioManager portlet.

<urn:getPortletProperties xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portletFolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:names xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/></urn:getPortletProperties>

Message 22: Get Portlet Property Description Request

The portfolioManager portlet has two properties viz tickerSymbols and refreshInterval. P Inc therefore returns the following response:

<urn:getPortletPropertyDescriptionResponse xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:modelDescription> <urn:propertyDescriptions type="xs:string" name="tickerSymbols"> <urn:label xml:lang="en"> <urn:value>Ticker Symbols</urn:value> </urn:label> </urn:propertyDescriptions> <urn:propertyDescriptions type="xs:string" name="refreshInterval"> <urn:label xml:lang="en"> <urn:value>Refresh Interval</urn:value>


5

10

15

20

25

30

35

40

45

5

</urn:label> </urn:propertyDescriptions> </urn:modelDescription></urn:getPortletPropertyDescriptionResponse>

Message 23: Portlet Property Description ResponseThis description indicates the description of the two properties associated with the portfolioManager portlet. Each property description also indicates the schema type of the property. In this specific scenario, both properties are of type XML schema type “string”. The type helps the Consumer in preparing a user interface for entering values for the properties. In addition to the type, a Producer may optionally supply a label and a hint. In the above message, labels provide a short description of each property.

Now consider the following scenario.

C Inc can use this description to design, for example, a HTML form with two text fields for displaying and updating tickerSymbols and refreshInterval properties.

A user of C Inc would like to update the tickerSymbols and and the refreshInterval using the page setup by C Inc.

C Inc sends a getPortpetPropertiesgetPortletProperties() request to P Inc to obtain the current values of the properties. C Inc uses the returned property values to display a form filled with the current values.

User enters new values for the properties, and submits the form. C Inc sends a setPortletProperties() request to P Inc to update the values of the properties.

Scenario 7: Setting Portlet Properties

In this scenario, note that the portlet with handle portfolioManager is a producer offered portlet. A producer offered portlet is one that is offered in the service description response with the same portlet handle. It is very likely that several Consumers and users share the same producer offered portlets. Any persistent state changes made to a producer offered portlet would therefore be shared by all its usages. In our scenario, since the properties associated with the portfolioManager portlet are specific to each user, P Inc cannot directly update the properties for the portfolioManager portlet. Instead, P Inc first clones the portlet, and associates the new property values with the cloned portlet.

This sequence of interactions is shown in Figure 3


5

10

15

20

25

30

35

40

5

Figure 3: Setting Portlet Properties With Implicit Cloning

The messages are as follows.

C Inc sends the following message to get the current (the default) values of properties associated with the portfolioManager portlet.

<urn:getPortletProperties xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:names xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/></urn:getPortletProperties>

Message 24: Get Portlet Properties Request

In this request, the value of the portlet handle is the same that of the portfolio manager portlet offered in the service description of P Inc. Also note the names element in this request. When this element is set “nil”, this request implies that the Producer must return values for all properties associated with the portlet. In case the Consumer is interested only in the values of certain properties, the Consumer may specify the names for which it needs values. In the following request, C Inc specifies the tickerSymbols property.


5

10

15

20

25

5


Figure is incorrect. Consumer must do a preclone here.

<urn:getPortletProperties xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/ <urn:names>tickerSymbols</urn:names></urn:getPortletProperties>

Message 25: Get Portlet Properties Request (For Specific Properties)

The default value of the tickerSymbols property is “AMZN” and the default value of the refreshInterval field is 180 seconds. For the request in Message , P Inc returns the following response with these values.<urn:getPortletPropertiesResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:properties name="tickerSymbols"> <urn:stringValue>AMZN</urn:stringValue> </urn:properties> <urn:properties name="refreshInterval"> <urn:stringValue>180</urn:stringValue> </urn:properties></urn:getPortletPropertiesResponse>

Message 26: Get Portlet Properties Response

C Inc can now display an HTML form with the current values filled in. After the user updates the form with new values (say, “AMZN, YHOO” for the tickerSymbol property and “60” secs for the refreshInterval property), C Inc sends the following request to P Inc.

<urn:setPortletProperties xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/> <urn:propertyList> <urn:properties name="tickerSymbols"> <urn:stringValue>AMZN, YHOO</urn:stringValue> </urn:properties> <urn:properties name="refreshInterval"> <urn:stringValue>60</urn:stringValue> </urn:properties> </urn:propertyList>


5

10

15

20

25

30

35

40

45

50

5


Multiple properties. Call it "tickerSymbolList". No comma between elements in a list. Don't have to introduce a list type here, but could use it like one.


Suggests to make one of the properties as int.

</urn:setPortletProperties>

Message 27: Set Portlet Properties Request

Since the portlet handle “portfolioManager” is producer-offered, P Inc implicitly clones the portlet before updating the properties. P Inc returns the updated portlet handle in its response, as shown below.

<urn:setPortletPropertiesResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:portletHandle>portfolioManager.1</urn:portletHandle></urn:setPortletPropertiesResponse>

Message 28: Set Portlet Properties Response

This response includes the handle of the cloned portlet “portfolioManager.1”. To associate the customized properties to the user, C Inc must use the cloned portlet handle instead of the original handle in subsequent requests made to P Inc for that user. P Inc may not clone the portlet on subsequent requests to set portlet properties.

If the Producer is unable to persistently update portlet properties, the Producer may serialize updated properties and return those as portletState in the setPortletPropertiesResponse.

When a Consumer receives such portletState during implicit/explicit cloning, the Consumer is required to supply the same with PortletContext in all future invocations for that portlet.

In the above scenario, P Inc cloned the portlet implicitly when C Inc attempted to update properties of a producer offered portlet. Instead, C Inc may first request P Inc to clone the portlet, and then set the properties.

Consider the following scenario that sets portlet properties after explicitly cloning the portlet.

A user requests C Inc to setup a page to access the portfolioManager portlet. C Inc sends a clonePortlet() request to P Inc to clone the portlet.

The user subsequently follows Scenario 7 to customize the portfolioManager portlet.

Scenario 8: Setting Properties with Explicit Cloning

The following sequence shows the sequence of interactions for setting portlet properties with explicit cloning.


5

10

15

20

25

30

35

40

5


Implicit cloning is not allowed during setPortletProperties. The consumer is required to make a decision on whether cloning is required before calling setPortletProperties. The consumer must send readWrite on setPortletProperties.

Figure 4: Setting Portlet Properties With Explicit Cloning

C Inc sends the following request to clone the portfolioManager portlet.

<urn:clonePortlet xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletContext> <urn:portletHandle>portfolioManager</urn:portletHandle> </urn:portletContext> <urn:userContext xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/></urn:clonePortlet>

Message 29: Clone Portlet RequestP Inc creates a clone of the portfolioManager portlet, and returns the following response with a new portlet handle.

<urn:clonePortletResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:portletHandle>portfolioManager.1</urn:portletHandle></urn:clonePortletResponse>

Message 30: Clone Portlet ResponseThe returned portlet handle is associated with a consumer created portlet, created by explicitly cloning a producer offered portlet.

C Inc now uses the new portlet handle during all subsequent requests for the portfolioManager portlet for that user. Note that C Inc may also use the new portlet handle while calling getPortletDescription() to get a description of the portlet.

In the above scenarios, portlets are cloned to associate customizations of portlet properties. In order to associate such customizations with cloned portlets, the Producer may have to manage some persistent state for the duration of the usage of that customization. Once the Consumer determines that a given customization is no longer in use, the Consumer may request the Producer to destroy the portlet.

The destroyPortlets() operation can be used to destroy one more consumer created portlets. Consider the following scenario.Web Services for Remote Portlets 1.0 Primer Page 49 of 61

5

10

15

20

25

30

35

5


Incorrect caption for Message 30.

A user requests C Inc to terminate his user account with C Inc. Since that user’s customizations are no longer required, C Inc sends a request P Inc to destroy portlets cloned for that user.

Scenario 9: Destroy Portlets

In order to destroy portlets, C Inc sends the following request to P Inc.

<urn:destroyPortlets xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:registrationContext> <urn:registrationHandle>CIncRegnHandle</urn:registrationHandle> </urn:registrationContext> <urn:portletHandles>portfolioManager.</urn:portletHandles></urn:destroyPortlets>

Scenario 10: Destroy Portlets Request

Note that C Inc may send more than one portlet handles in this request, so that several portlets can be destroyed in a single request.

Upon verifying that the portlet handle refers to a consumer created portlet, P Inc may delete any customizations associated with each portlet being destroyed, and return the following response.

<urn:destroyPortletsResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"/>

Message 31: Destroy Portlets Response

However, if the Consumer attempts to destroy a producer offered portlet, or if the Producer fails to destroy a portlet due to some internal failure, the Producer may include the portlets that it failed to destroy and a reason for the failure in the destroyPortletsResponse. The following message shows the response from P Inc when C Inc attempts to destroy the producer offered portlet with handle portfolioManager.

<urn:destroyPortletsResponse xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <urn:destroyFailed> <urn:portletHandle>portfolioManager</urn:portletHandle> <urn:reason>Producer offered portlet. Can't be destroyed</urn:reason> </urn:destroyFailed></urn:destroyPortletsResponse>

Message 32: Destroy Portlets Response When Failed

This response indicates the P Inc failed to destroy the producer offered portlet with handle portfolioManager.


5

10

15

20

25

30

35

40

45

5


Drop destroy failed message. Because consumer is supposed to know if a portlet is a POP.

After a consumer created portlet has been destroyed, the Consumer can no longer use the portlet with that handle.

The following sequence illustrates a Consumer aggregating cloned portlets for several users, and destroying the cloned portlets when such portlets are no longer required.

Figure 5: Cloning and Destroy for Managing Portlet Customizations

8.2 FaultsConsumers invoking operations on the portlet management interface must be prepared to handle the following faults:AccessDenied: A Producer throws this fault when it is unable to process a given request due to internal security violations.InvalidUserCategory: A Producer throws this fault when user categories supplied (if any) by the Consumer are invalid.InconsistentParameters: A Producer throws this fault when the request data is not conistent.InvalidRegistration: A producer throws this fault when the registration data supplied by the consumer is not validMissingParameters: A Producer throws this fault when any required data is missing.

OperationFailed: A producer throws this fault when it fails to process the operation.

InvalidHandle: A Producer throws this fault when any supplied handle is not valid. For example, a Producer throws this fault the supplied protletHandleportletHandle is no longer valid.


5

10

15

20

25

5

9 Use ProfilesThe Use Profile describes at a high level the basic functionality of a Producer or Consumer implementation. These are to be regarded as merely a general guideline. Implementers will likely compose their implementation by selecting from a “palette” of functionality, and later sections of this primer lay out these use profiles across several functional axes. An implementation can therefore be said to conform across potentially several different functional areas, offering advanced features in some areas while remaining “simple” or even “base” in others.A Consumer and Producer have different motivations in achieving higher levels. A Producer need only implement the functionality required by the portlets it is offering. Unless a Consumer knows that it will only be consuming portlets of a given level, it should provide all levels so that any portlet can function properly. The Consumer should not assume that there is “graceful degradation”, in other words, if the Consumer does not provide, say, registration, the portlet may not function at all. Also note that there is not a one-to one correspondence with Producer Levels and Consumer Levels; e.g. the Base consumer level is expected to handle initCookie, which the Base Producer level does not use cookies.

9.1 Producer Levels

9.1.1 BaseThe base level producer is suitable for simple read-only portlets. As it only implements the MUST interfaces (Markup and ServiceDescription), there is no registration and no portlet management. In our example above, the Base level would be sufficient to handle the interaction between P Inc and C Inc up to registration.No state is required in the Base level. This means that no session information will used; if the producer wants to store state, the producer should use navigational state. There is no cloning at the base level; so all portlets would be read-only. No initialization is required, so the service description should not return initCookie.The producer at the base level is not required to rewrite URLS in markup.Implements only the MUST interfacesNo state (session or persistent); uses opaque mechanism to send state back to ConsumerNo cloningNo initialization requiredDoes not rewrite URLs in markupDoes not require registration

9.1.2 Simple In the simple implementation, the Producer can store state in cookies. This means it can set requiresInitCookie in getServiceDescription.The simple level supports cloning, so it can support customizable portlets as in with P Inc. above. The simple level may require out-of-band registration. Note that this does not cover the scenario with P Inc above, as out-of-band registration means that the RegistrationHandle is created by other means than the register call. In addition to navigational state, the simple level producer can also use session state. See section 5.2 of the primer for returning the SessionContext in getMarkupResponse.


5

10

15

20

25

30

35

40

5


Clinton volunteered to look at Use Profile sections.

May request initialization; could store state in cookiesSupports cloningMay require registration (out-of-band).Session state; creates and sends session handles to the Consumer

9.1.3 ComplexFor the complex level, the producer may rewrite URLS. This requires Consumer templates, which requires a Consumer at complex level. Note that the Markup example with P Inc above just uses Consumer and not Producer rewriting. The complex level producer may offer both in-band and out-of band registration. Note that the example with P Inc. uses in-band registration. The complex level producer uses persistent local state, meaning that the state for cloned portlets will be saved on the producer. The complex level producer may support grouping of portlets. See section 5.1.11 and 5.1.18 in the specification for how grouping is used. The complex level producer supports cache validation. See the CacheControl section in 6.1.5 of the specification and MarkupParams type in section 6.1.9 of the specification on how the validate tag is used. An analogy with HTTP would be the use of Etags in addition to LastModified headers.May rewrite URLs (requires Consumer templates)May offer both in-band and out-of- band registrationPersistent local stateMay support grouping of portletsCache validation

9.2 Consumer Levels

9.2.1 BaseThe base level Consumer implements only the MUST interfaces, namely Markup and ServiceDescription. So a base level Consumer would not be able to display portlets from Producers that return true for requiresRegistration in getServiceDescription. The base level Consumer only needs to implement wsrp:view mode and wsrp:normal window state, which basically limits it to read-only portlets.No user information is supplied to the Producer. While the producer may give degraded functionality, the Consumer cannot assume that the Producer may not simply fault in response. The base level Consumer rewrites urls (Consumer rewriting). The base level cookie support includes initializing the Producer if required- that is, if the portlet has returned true for requiresInitCookie in getServiceDescription, and handling Producer cookies. The only markup type required by the base level Consumer is text/html. As the base level Consumer does not support cloning, the PortletStateChange field must be set to “readOnly”. This may limit the funcationality of portlets that offer personalization. See section 6.3.2 in the specification.Implements only the MUST interfacesVIEW mode, NORMAL window state onlySupplies no user information (portlet may fault or degrade functionality in response).Rewrites URLsInitializes the Producer if required (initCookie)


5

10

15

20

25

30

35

40

5

Handles Producer cookiesLimited markup types (e.g. html)Does not clone (“readOnly”; may limit functionality of portlets that offer personalization)No in-band registration

9.2.2 SimpleThe simple level Consumer adds support for standard modes and window states, namely wsrp:edit, wsrp:help, and wsrp:preview modes, and wsrp:maximized, wsrp:minimized and wsrp:solo window states. See section 5.6 of the primer for a discussion on modes. The simple level Consumer supports in-band registration, as in the example with C Inc. above. Basic user information, in the form of identity and authorization type, is supplied. See userAuthentication in section 6.1.2 of the specification.The Consumer should support caching using the CacheControl structure in section 6.1.5 of the specification. Also see section 8.3 of the primer.The Consumer may explicitly clone portlets, as well as handle implicit clones, as when the Producer returns “cloneBeforeWrite”. See section 5.3 of primer for more detail on “cloneBeforeWrite”.Support for standard modes and window statesSupport for in-band registrationSupplies basic user information (e.g., identity and authorization type)Caching according to Producer-supplied cache control.May explicitly clone portlets.Handles implicit clones (“cloneBeforeWrite”).

9.2.3 Complex The Complex level Consumer may supply templates to a Producer that provides Producer rewriting. See section 6.1.6 of the specification for the templates required. The Complex level consumer should be able to handle multiple markup types, for example wml in addition to text/html. In addition, the Consumer should support localization. The Complex level consumer should support the PortletManagement Interface, which may include creating a custom UI for property management. Section 6 of the primer above details why the C Inc. would create such a UI.

The Complex consumer supports complex user management. See section 11 of the specification on User Information, UserProfile information in the register call, and section 6.1.17 of the specification on user profiles. Custom modes and window states may be supported. See consumerWindowStates for how the Consumer supplies custom window states in the register() call, customWindowStateDescriptions, for how the Producer lists custom window states in the ServiceDescription type.

Supports user categories- note that user categories do not necessarily correspond to levels of user access. See section 6.10 in the specification.May supply URL rewrite templates to a Producer that is capable of rewriting URLs in portlet markup.Multiple markup types (e.g. html and wml)Complex user management, willing to supply standard/extended user attributes May support custom window states and/or modes.


5

10

15

20

25

30

35

40

45

5

Multiple levels of user access (user categories)LocalizationMay use explicit property-setting mechanism; create custom UI for property management.

10Basic Topics/Issues10.1 Fault HandlingWSRP specifies a number of faults that a Producer may return in response to various requests from a Consumer. If you are setting up a Consumer to aggregate portlets from a Producer, knowledge of the implication of these faults would help debug any problems. Note that Producers may return additional faults as dictated by underlying web service stack.Each WSRP fault has an associated faultcode. Here is an example message from a Producer that requires registration in response to a request from a Consumer without the registrationContext.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <soapenv:Fault xmlns:urn="urn:oasis:names:tc:wsrp:v1:types"> <faultcode>urn:InvalidRegistration</faultcode> <faultstring>Registration is required.</faultstring> <detail> <urn:InvalidRegistration/> </detail> </soapenv:Fault> </soapenv:Body></soapenv:Envelope>

Message 21: Fault ResponseThe faultstring in this message explains that the Consumer must supply registrationContext with the request. Also note the detail element. This element contains the name of the faultcode qualified by “oasis:names:tc:wsrp:v1:types” namespace.

10.1.1 AccessDenied FaultA Producer may return this fault when the Producer is unable to provide access to a portlet for a given operation due to security policy reasons.Action: Since such security policy restrictions are implementation specific, consult the entity hosting the Producer to determine an appropriate action.

10.1.2 InconsistentParameters FaultA Producer may return the InconsistentParameters fault when a Consumer tries to access a portlet with a portletHandle that was created during a different registrationContext than the one the Consumer supplied.


5

10

15

20

25

30

35

5


9.2 to include all faults. We limit complexity of fault handling. DONE. To better motivate the reader, also discussed possible actions.

, 01/03/-1,

I propose that we merge Section 8 and Section 9, and name the merged section as “Practical Considerations” or equivalent.

Action: Make sure that the portletHandle included in the request corresponds to either a portletHandle returned in the service description response, or one returned during a performBlockingInteraction or clonePortlet operations invoked using the same registrationContext. If not, use the correct registrationContext or reset the portletHandle to one of those offered in the service description response.

10.1.3 InvalidRegistration FaultThis fault indicates that either the Consumer did not supply a registrationContext when registration is required, or the supplied registrationContext is invalid.

Action: Check the Producer’s service description to see if the Producer requires registration. If so, register the Consumer with the Producer and resend the request with the registrationContext. If you have already registered your Consumer with the Producer, make sure that the registrationContext is included in the request. Also make sure if the registrationContext is the same as the one returned by the Producer. If the Producer still returns the same fault, check the message to see if you need to reregister the Consumer or modify the existing registration.

10.1.4 InvalidCookie FaultHTTP cookies are transient and may become invalid. A Producer returns this fault when the Consumer supplied cookie is no longer valid. Action: Invoke the initCookie operation again and then invoke the operation that caused this fault with the new cookies. Since cookies returned by the Producer may be related to the session IDs returned in an implementation-specific manner, resend any data stored that the Producer stores in the session. For example, if the Producer stores URL templates and user context data in HTTP sessions, resend URL templates and user context data with the request.

10.1.5 InvalidHandle FaultA Producer returns this fault when the Consumer supplied portletHandle is invalid.

Action: Make sure that the portletHandle included in the request corresponds to either a portletHandle returned in the Service Description response, or one returned during a performBlockingInteraction or clonePortlet operations invoked using the same registrationContext.

10.1.6 InvalidSession FaultA Producer returns this fault when a Consumer-supplied session ID is invalid.Action: Invoke the same operation without the sessionID and with any data that the Producer stores in the session. For example, if the Producer stores URL templates and user context data in HTTP sessions, resend URL templates and user context data with the request.

10.1.7 InvalidUserCategory FaultA Producer returns this fault when a Consumer supplied userCategory name is not valid. Note that Consumer should not supply user categories not recognized by Producers.Action: Make sure that the userCategory is one of those supplied by the Producer in its Service Description response.

10.1.8 MissingParameters FaultA Producer returns this fault when some required data is missing in the request.


5

10

15

20

25

30

35

40

5

, 01/03/-1,

Also for invalid registrationHandles?

Action: Since the set of parameters required are specific to each operation, refer to the description of the operation and make sure that all the required parameters are included in the request.

10.1.9 OperationFailed FaultThis is the most generic fault that a Producer can return for any request from a Consumer. In general, well-behaving Producers return this fault only when the condition that caused the fault cannot be described with any other WSRP fault. Action: If you encounter this fault, look into the faultstring for any clues, and if no meaningful explanation is found, contact the entity hosting the Producer for help.

10.1.10 PortletStateChangeRequired FaultA Producer throws this fault when the portlet needs to update its persistent state during a performBlockingInteraction but it cannot allow it since the consumer is ready for state changes.During performBlockingInteraction, persistent state changes are dictated by the portletStateChange flag in the request. When the value of this flag is set to readWrite or cloneBeforeWrite, the producer can allow the portlet to make persistent state changes. A persistent state change may cause the Producer to return a new portletContext. In case the Consumer is not capable of accepting the new portletContext, it may instead set the value of the portletStateChange flag to readOnly, which would cause this fault.

Action: If possible, configure the Consumer to allow state changes. Note that portlets may not function correctly when prevented from making persistent state changes. If you find that the portlet is not usable without persistent state changes and if you are unable to configure the Consumer to allow state changes, consider not using the portlet.

10.1.11 UnsupportedLocale FaultA Producer may throw this fault when a portlet is unable to generate the markup in the requested locale.Action: Since the portlet is not capable of generating markup in the requested locale, restrict the Consumer to supply one of the locales supported by the portlet.

10.1.12 UnsupportedMimeType FaultThis is similar to the UnsupportedLocale fault, and a Producer throws this fault when a portlet cannot generate markup in the requested MIME type.Action: Since the portlet is not capable of generating markup in the requested MIME type, restrict the Consumer to supply one of the MIME types supported by the portlet.

10.1.13 UnsupportedMode FaultA Producer throws this fault when a portlet cannot be invoked in a given mode.Action: Restrict the Consumer to supply a mode supported by the portlet

10.1.14 UnsupportedWindowState FaultA Producer throws this fault when a portlet cannot be invoked in a given window state.Action: Restrict the Consumer to supply a window state supported by the portlet


5

10

15

20

25

30

35

5

, 01/03/-1,

The spec talks about “generating markup”. But this fault also applies to plain interactions as well.

10.2MarkupOperationFailed semanticsReference portlet style guide?

10.3Fault HandlingIn the Markup interface, operations are tied to end-user activity. Due to the volume and concurrent nature of these requests, any fault should be used as a clue to the Consumer as to the “health” of the target Producer/portlet. A fault-tolerant Consumer implementation will not allow performance to degrade by continually firing requests at a non-responding or malfunctioning port/portletHandle, thereby incurring timeout penalties when rendering pages.

These faults should be interpreted by Consumers as indicating a serious problem with this Producer. Suggested corrective action in ()’s:

InvalidRegistration (Cancel request; re-register/re-bind portlets?)InvalidHandle (Cancel request; destroyClone() if CCP handle; re-bind)

These are routine faults that could occur due to ordinary Producer conditions.InvalidCookie (Re-init Producer cookie; re-try request)InvalidSession (Re-init session; re-try request)

These are faults that shouldn’t occur ordinarily, and may indicate a problem with the Consumer implementation. These indicate a need to troubleshoot the implementation:

InconsistentParametersMissingParameters

These are operational faults that may indicate a transient condition at the Producer:

OperationFailed (Capture/log fault details; don’t retry request; if continually thrown, may indicate a more serious Producer issue)

These faults indicate a problem with the end-user capabilities or details of the request, and will probably recur until the Consumer takes corrective action:

AccessDenied (Bad registration context?)InvalidUserCategory (correct user category)UnsupportedLocale (correct locale)UnsupportedMimeType (correct mime type)UnsupportedMode (correct mode)UnsupportedWindowState (correct window state)


5

10

15

20

25

30

35

40

5


9.2 to include all faults. We limit complexity of fault handling.


Not required

10.4Caching

10.5PersistenceOpaque state: This is always scoped by the Producer to a portletHandle. If a Consumer shares a portletHandle among multiple users, this may introduce problems if the Producer expects to persist user-specific state; how to isolate this user’s activity from others? It is suggested that when the Producer detects this condition, that it clones the portlet (if Consumer specified cloneOnWrite semantics in its interaction request context), or throws a PortletStateChangeRequired fault (if Consumer specifies readOnly, or even readWrite). Consumers, to be safe, should NOT rely on a Producer to undertake this level of state change detection, unless it has specific knowledge of that Producer’s capabilities (i.e. it implements the PortletManagementInterface; interpretation for hasUserSpecificState?) The Consumer should either explicitly clone a portlet (safest) for each end-user that wants to utilize it, or use the cloneOnWrite semantics (not quite as safe, depending on how Producer makes this determination, although if Producer sets hasUserSpecificState==true, this may indicate the Producer may manage user-specific state properly). Cloning, including semantics for hasUserSpecificState

10.6StatefulnessCookie: Cookies are not recommended as a generic means of storing state; even though the Consumer is required to honor Producer-set cookies. The main use case is to enable cookie-based (http) load balancers to match requests to specific Producer nodes, so that session continuity is not lost. Navigational: Current web applications make use of the request query string to encode state, and navigational state can be considered the WSRP equivalent. As with the query string, parameter names and values in navigational state must be considered visible (although it could certainly be encrypted), and so privacy considerations may be one factor in determining whether something should be encoded as navigational state, rather than an alternative such as session state. The primary use case for supporting navigational state is to facilitate the ability of a user to “bookmark” a portlet, permitting the user to easily navigate to a known point in the portlet’s presentation. So, the main considerations for portlet implementers in determining what, if anything, to put in navigational state, come down to questions of a) what navigational “points” are available in the portlet presentation that a user may be interested in bookmarking, and b) what parameters would be needed to “prime” the necessary state for the portlet to render the exact markup required to recreate the presentation for each of these “points”.Session: As in today’s web application environments, WSRP supports the concept of sessions, and therefore portlets are able to persist state that is applicable to a “session”, in whatever sense that’s important to the implementation. The Consumer must assist the Producer in managing WSRP sessions, however, in much the same way today’s servlet environments depend on a session key being passed with each request (typically encoded in a cookie). The WSRP session ID may be generated by the Producer during a sequence of Consumer requests, and the Consumer must re-send this ID in each subsequent request; otherwise, the portlet implementation would have a difficult time matching the inbound request to the correct session context. When does a Producer need to generate a new session ID? There is no hard and fast rule. One approach may be to replicate the behavior of java servlets, and generate a new session ID on the initial request, which the Consumer would then “join” by including the session ID in subsequent requests.


5

10

15

20

25

30

35

40

45

5


Subbu to collapse 9.4 and 9.5 into one. Also include motivations.


Atul to write.

10.7Modes/Window StatesCarry JSR 168-specific modes. There is already overlap between 168 and WSRP modes and window states (WSRP is a superset):Common modes: view, help, edit, previewCommon window states: normal, maximized, minimized

Implementations that need custom modes/window states should ensure that these are mutually understood between Consumer and Producer, and unambiguous.

10.8URL Rewriting

11 Advanced Topics/Issues11.1 User Profile and personalizationUnauthenticated (“guest”) accessuserContextKey == UserCategory, for conveying common attributes for a class of users

11.2Localization and Internationalization

11.3SecuritySSL (Client)HTTP DigestSAML/XACML (not for 1.0)

11.4 ExtensionsThe WSRP specification has been designed such that any WSRP data structure can include additional data known as an “extension”. Extensions address the need for implementing specific use cases not specified by WSRP. Extensions are implementation-specific. A Producer and Consumer must agree to the purpose and semantics of the extension before extending any WSRP data structure. Note that Producers using extensions are not guaranteed to function correctly if a Consumer does not supply extended data required by the Producer. If you are implementing a Producer, consider making any extensions optional so that the Producer can interoperate with Consumers that do not supply such extensions.Why? When? etc.

11.5Carrying custom modesJSR 168?


5

10

15

20

25

30

35

5


Move to markup section.


Drop


Subbu to elaborate


Discuss stack related issues. Refer to archives for details.


Discuss common pitfalls, such as cookies, sessions, uploads, redirect etc. Also include the list of issues discovered.


Move to markup section.


Drop this.

WSRP: SOLO window state. Interpret as maximized for JSR 168?Implementation-specific: These should be in an implementation-specific namespace.

If a Consumer does not understand a portlet’s custom mode/window state, it is unlikely to request markup using that mode/ws. This should be ok, given the fact the portlet MUST support a minimal set of standard modes/ws.

A Consumer could have its own set of custom modes and window states, and attempt to request a portlet render in one of these. If the portlet does not comprehend, it should throw an appropriate fault message. However, it could be beneficial for the portlet to also render the requested markup anyway, just in a standard mode/ws such as view/normal. That way, the Consumer still has markup it can use to build the end-user page (rather than just an error message), and it has fault information it can use to take corrective action regarding its use of custom modes/ws. However, the portlet also may have its own implementation restrictions that dictate a stricter application of modes/window states, and so it is ultimately the prerogative of the portlet implementation not to generate any markup in this case.

11.6 Multipart uploadProducer must be prepared to reconstruct the input from a varietly of representations (single UploadContext, multiple UploadContexts)Minimal required attributes/headers?


5

10

15

20

5

Documents

Web Services for Remote Portlets 1.0 Primer · Web viewHTTP cookies are transient and may become invalid. A Producer returns this fault when the Consumer supplied cookie is no longer