Web Services for Remote Portlets Specification

Version 0.95

4/24/2003

Web Services for Remote Portlets
Specification
Committee Specification 0.95, 24 April 2003
5

Document identifier:wsrp-specification-1.0 (Word)
Location:
http://www.oasis-open.org/committees/wsia
http://www.oasis-open.org/committees/wsrp
10

15

20

Editors:
Alan Kropp, Vignette Corporation <akropp@vignette.com>
Carsten Leue, IBM Corporation <cleue@de.ibm.com>
Rich Thompson, IBM Corporation <richt2@us.ibm.com>
Contributors:
Chris Braun, Novell <cbraun@silverstream.com>
Jeff Broberg, Novell <jbroberg@silverstream.com>
Mark Cassidy, Netegrity <mcassidy@Netegrity.com>
Michael Freedman, Oracle Corporation <Michael.Freedman@oracle.com>
Timothy N. Jones, CrossWeave <tim@crossweave.com>
Thomas Schaeck, IBM Corporation <schaeck@de.ibm.com>
Gil Tayar, WebCollage <Gil.Tayar@webcollage.com>
Abstract:

25

Integration of remote content and application logic into an End-User presentation has been atask requiring significant custom programming effort. Typically, vendors of aggregating
applications, such as a portal, write special adapters for applications and content providers toaccommodate the variety of different interfaces and protocols those providers use. The goal ofthis specification is to enable an application designer or administrator to pick from a rich choiceof compliant remote content and application providers, and integrate them with just a few
mouse clicks and no programming effort.

30

35This specification is a joint effort of two OASIS technical committees. Web Services forInteractive Applications (WSIA) and Web Services for Remote Portals (WSRP) aim to simplify
the integration effort through a standard set of web service interfaces allowing integrating
applications to quickly exploit new web services as they become available. The joint authoringof these interfaces by WSRP and WSIA allows maximum reuse of presentation-oriented,
interactive web services while allowing the consuming applications to access a much richer setof standardized web services.

This joint standard layers on top of the existing web services stack, utilizing existing web
services standards and will leverage emerging web service standards (such as security) as
they become available. The interfaces are defined using the Web Services Description
Language (WSDL).
5
Status:This version is the initial Committee Specification level of the public specification. Comments
about points needing clarification are much appreciated and may be emailed to Rich
Thompson.
10

15

If you are on the wsia@lists.oasis-open.org or wsrp@lists.oasis-open.org list for committee
members, send comments there. If you are not on that list, subscribe to the wsiacomment@lists.oasis-open.org or wsrp-comment@lists.oasis-open.org list and send comments
there. To subscribe, send an email message to wsia-comment-request@lists.oasis-open.org or
wsrp-comment-request@lists.oasis-open.org with the word "subscribe" as the body of themessage.
The errata page for this specification is at http://www.oasisopen.org/committees/wsrp/specifications/version1/wsrp-specification-1.0-cs-errata.html.

20
Copyright © 2001, 2002 The Organization for the Advancement of Structured Information Standards[OASIS]Web Services for Remote Portlets Specification

2

Table of Contents
1

Introduction......................................................................................................................................... 6
1.1
Motivation...................................................................................................................................... 6
1.2
Actors............................................................................................................................................. 7
1.2.1
Portlet..................................................................................................................................... 7
Producer................................................................................................................................ 7
1.2.2
1.2.3
Consumer.............................................................................................................................. 8
1.2.4
End-User ............................................................................................................................... 8
1.3
Typical Process Flow .................................................................................................................. 82

Terminology ........................................................................................................................................ 9

3

General Considerations ................................................................................................................... 9
3.1
Related Standards ..................................................................................................................... 10
3.1.1
Existing Standards............................................................................................................. 10
3.1.2
Emerging Standards.......................................................................................................... 10
3.2Foundations ................................................................................................................................ 10
Data Objects ............................................................................................................................... 11
3.3
3.4
Lifecycles .................................................................................................................................... 11
3.5
Scopes......................................................................................................................................... 11
3.6
Types of Stateful Information ................................................................................................... 12
3.7
Persistence and statefulness ................................................................................................... 12
Producer Mediated Sharing...................................................................................................... 13
3.8
3.9
Information Passing Mechanisms ........................................................................................... 13
3.10 Two-step protocol ...................................................................................................................... 13
3.11 Transport Issues ........................................................................................................................ 14
3.12 Load Balancing........................................................................................................................... 144Interface Overview........................................................................................................................... 14
4.1
Service Description Operations ............................................................................................... 14
4.2
Markup Operations .................................................................................................................... 14
4.3
Registration Operations ............................................................................................................ 15
4.4
Portlet Management Operations.............................................................................................. 15

5Service Description Interface ....................................................................................................... 16
5.1
Data Structures .......................................................................................................................... 16
5.1.1
Extension Type................................................................................................................... 16
5.1.2
Handle Type ....................................................................................................................... 16
5.1.3
Key Type ............................................................................................................................. 17
5.1.4
ID Type ................................................................................................................................ 17
5.1.5
LocalizedString Type ......................................................................................................... 17
5.1.6
ResourceValue Type ......................................................................................................... 18
5.1.7
Resource Type ................................................................................................................... 18
5.1.8
ResourceList Type............................................................................................................. 18
ItemDescription Type......................................................................................................... 18
5.1.9
5.1.10 MarkupType Type .............................................................................................................. 19
5.1.11 PortletDescription Type..................................................................................................... 20
5.1.12 Property Type ..................................................................................................................... 22
5.1.13 ResetProperty Type........................................................................................................... 22
5.1.14 PropertyList Type............................................................................................................... 22
5.1.15 PropertyDescription Type ................................................................................................. 23
5.1.16 ModelTypes Type .............................................................................................................. 23
5.1.17 ModelDescription Type ..................................................................................................... 23
5.1.18 CookieProtocol Type ......................................................................................................... 24
5.1.19 ServiceDescription Type ................................................................................................... 24

5

10

15

20

25

30

35

40

45

50

Web Services for Remote Portlets Specification35.1.20 RegistrationState Type...................................................................................................... 25
5.1.21 RegistrationContext Type ................................................................................................. 25
5.1.22 desiredLocales ................................................................................................................... 26
5.2
getServiceDescription() Operation .......................................................................................... 26
5

6Markup Interface .............................................................................................................................. 27
6.1
Data Structures .......................................................................................................................... 27
6.1.1
SessionContext Type ........................................................................................................ 27
6.1.2
RuntimeContext Type........................................................................................................ 27
6.1.3
PortletContext Type ........................................................................................................... 28
6.1.4
Standard UserScopes ....................................................................................................... 29
CacheControl Type............................................................................................................ 29
6.1.5
6.1.6
Templates Type.................................................................................................................. 30
6.1.7
ClientData Type.................................................................................................................. 30
6.1.8
NamedString Type............................................................................................................. 31
6.1.9
MarkupParams Type ......................................................................................................... 31
6.1.10 MarkupContext Type ......................................................................................................... 33
6.1.11 MarkupResponse Type ..................................................................................................... 34
6.1.12 UpdateResponse Type ..................................................................................................... 34
6.1.13 BlockingInteractionResponse Type................................................................................. 35
6.1.14 StateChange Type............................................................................................................. 36
6.1.15 UploadContext Type.......................................................................................................... 36
6.1.16 InteractionParams Type.................................................................................................... 36
6.1.17 User Profile Types ............................................................................................................. 37
6.1.18 UserContext Type .............................................................................................................. 40
6.2
getMarkup() Operation .............................................................................................................. 41
Caching of markup fragments .......................................................................................... 41
6.2.1
6.3
Interaction Operations............................................................................................................... 41
6.3.1
performBlockingInteraction() Operation.......................................................................... 42
6.3.2
Updating Persistent Portlet State .................................................................................... 42
6.4
initCookie() Operation ............................................................................................................... 43
6.5
releaseSessions() Operation.................................................................................................... 44
6.6
Consumer Transitions across Bindings .................................................................................. 44
6.7
Stateful Portlet Scenarios ......................................................................................................... 44
6.7.1
No State............................................................................................................................... 44
6.7.2
Navigational State Only..................................................................................................... 45
6.7.3
Local state........................................................................................................................... 46
6.8
Modes .......................................................................................................................................... 47
6.8.1“wsrp:view” Mode............................................................................................................... 48
6.8.2“wsrp:edit” Mode ................................................................................................................ 48
6.8.3“wsrp:help” Mode ............................................................................................................... 48“wsrp:preview” Mode ......................................................................................................... 48
6.8.4
6.8.5
Custom Modes ................................................................................................................... 48
6.9
Window States ........................................................................................................................... 48
6.9.1“wsrp:normal” Window State ............................................................................................ 49
6.9.2“wsrp:minimized” Window State ...................................................................................... 49“wsrp:maximized” Window State ..................................................................................... 49
6.9.3
6.9.4
“wsrp:solo” Window State ................................................................................................. 49
6.9.5
Custom Window States..................................................................................................... 49
6.10 User Categories ......................................................................................................................... 50
6.10.1 User Category Assertions................................................................................................. 50

7

Registration Interface ..................................................................................................................... 50
7.1
Data Structures .......................................................................................................................... 50
7.1.1
RegistrationData Type....................................................................................................... 51
7.2
register() Operation.................................................................................................................... 52
7.3
modifyRegistration() Operation................................................................................................ 52

10

15

20

25

30

35

40

45

50

55

Web Services for Remote Portlets Specification

4

7.4
8

Portlet Management Interface ...................................................................................................... 53
8.1
Data Structures .......................................................................................................................... 53
8.1.1
DestroyFailed Type............................................................................................................ 53
8.1.2
DestroyPortletsResponse Type ....................................................................................... 53
8.1.3
PortletDescriptionResponse Type................................................................................... 54
8.1.4
PortletPropertyDescriptionResponse Type.................................................................... 54
8.2
getPortletDescription() Operation............................................................................................ 54
8.3
clonePortlet() Operation............................................................................................................ 55
8.4
destroyPortlets() Operation ...................................................................................................... 55
setPortletProperties() Operation.............................................................................................. 56
8.5
8.6
getPortletProperties() Operation.............................................................................................. 56
8.7
getPortletPropertyDescription() Operation............................................................................. 57

9Security .............................................................................................................................................. 57
9.1
Authentication of Consumer ..................................................................................................... 58
Confidentiality & Message Integrity......................................................................................... 58
9.2
9.3
Access control ............................................................................................................................ 58

5

10

15

20

25

30

35

40

deregister() Operation ............................................................................................................... 52

10
Markup............................................................................................................................................ 58
10.1 Encoding ..................................................................................................................................... 58
10.2 URL Considerations .................................................................................................................. 58
10.2.1 Consumer URL Rewriting ................................................................................................. 60
10.2.2 Producer URL Writing ....................................................................................................... 63
10.2.3 BNF Description of URL formats ..................................................................................... 65
10.2.4 Method=get in HTML forms.............................................................................................. 66
10.3 Namespace Encoding ............................................................................................................... 66
10.3.1 Consumer Rewriting .......................................................................................................... 66
10.3.2 Producer Writing ................................................................................................................ 66
10.4 Using Resources........................................................................................................................ 67
10.5 Markup Fragment Rules ........................................................................................................... 67
10.5.1 HTML ................................................................................................................................... 67
10.5.2 XHTML................................................................................................................................. 67
10.5.3 XHTML Basic...................................................................................................................... 68
10.6 CSS Style Definitions ................................................................................................................ 68
10.6.1 Links (Anchor) .................................................................................................................... 68
10.6.2 Fonts .................................................................................................................................... 69
10.6.3 Messages............................................................................................................................ 69
10.6.4 Sections............................................................................................................................... 69
10.6.5 Tables .................................................................................................................................. 70
10.6.6 Forms................................................................................................................................... 70
10.6.7 Menus .................................................................................................................................. 71
User Information .......................................................................................................................... 71
1111.1 Passing User Information ......................................................................................................... 74
11.2 User Identity................................................................................................................................ 74

45

12Constants ...................................................................................................................................... 75

13

Fault Messages ............................................................................................................................ 75

14

WSDL Interface Definition ......................................................................................................... 76

15
References .................................................................................................................................... 77
15.1 Normative.................................................................................................................................... 77
15.2 Non-Normative ........................................................................................................................... 77
50

Appendix A:

Glossary (Non-Normative)......................................................................................... 79

Appendix B:

Common Values (Non-Normative)........................................................................... 81

Web Services for Remote Portlets Specification

5

B.1

Standard User Categories ........................................................................................................ 81

Appendix C:

5

Data Structures List (Non-Normative) .................................................................... 82

Appendix D: Acknowledgments (Non-Normative)....................................................................... 83
D.1 WSIA committee members ........................................................................................................... 83
D.2 WSRP committee members.......................................................................................................... 84
Appendix E:

Revision History (Non-Normative)........................................................................... 85

Appendix F:

Notices............................................................................................................................ 86

1 Introduction
10

The Web Services for Remote Portlets specification defines a web service interface foraccessing and interacting with interactive presentation-oriented web services. It has been
produced through the joint efforts of the Web Services for Interactive Applications (WSIA) and
Web Services for Remote Portals (WSRP) OASIS Technical Committees. It is based on therequirements gathered by both committees and on the concrete proposals to both committees.

15
Scenarios that motivate WSRP/WSIA functionality include:

20

25

30

35

•

Portal servers providing portlets as presentation-oriented web services that can be usedby aggregation engines.

•

Portal servers consuming presentation-oriented web services provided by portal or nonportal content providers and integrating them into a portal framework.

However this description also applies to non-portal environments, mostly identified by the WSIA
use cases1. For additional details and documents, refer to the committee information available
at http://www.oasis-open.org/committees/wsrp/ and http://www.oasisopen.org/committees/wsia/.
This specification accounts for the fact that Producers (web services conforming to thisspecification) and Consumers (applications consuming Producers in a manner conforming tothis specification) may be implemented on very different platforms, be it as a [J2EE] based web
service, a web service implemented on Microsoft's [.Net] platform or a portlet published directly
by a portal [A100]. Special attention has been taken to ensure this platform independence.
These web services are built on standard technologies, including [SSL/TLS], [URI/URL],[WSDL] and [SOAP], and expects to leverage future applicable Web Service standards, suchas WS-Security and WS-Policy (see section 3.1) [A102] in future versions.

1.1 Motivation
Portals and other Web applications render and aggregate information from different sources
and provide it in a compact and easily consumable form to an End-User.

1

http://www.oasis-open.org/committees/wsia/use_cases/index.shtml

Web Services for Remote Portlets Specification

6

5

10

Among typical sources of information are web services. Traditional data-oriented web services,
however, require aggregating applications to provide specific presentation logic for each ofthese web services. Furthermore, each aggregating application communicates with each webservice via its unique interface. This approach is not well suited to dynamic integration ofbusiness applications and content as a plug-and-play solution.
This specification solves this problem by introducing a presentation-oriented web service
interface that allows the inclusion of and interaction with content from a web service. Such apresentation-oriented web service provides both application logic and presentation logic. This
specification provides a common protocol and a set of interfaces for presentation-oriented web
services. Thus, aggregating applications can easily adopt these web services by utilizing
generic proxy code.

1.2 Actors
15This protocol describes the conversation between Producers and Consumers on behalf of EndUsers (clients of the Consumer). Producers are presentation-oriented web services that hostPortlets which are able to render markup fragments and process user interaction requests.
Consumers use these web services to present the generated markup to End-Users andmanage the user’s interaction with the markup.

1.2.1 Portlet
20

Portlets are hosted by Producer web services and generate markup as well as processing
interactions with that markup. In general a Portlet includes both logic conforming to somespecification of the Producer’s environment and a particular configuration of any settings orproperties the Portlet exposes.

1.2.2 Producer
25

Producers are modeled as containers of Portlets. The Producer provides a set of web service
interfaces, including:•Self Description: A required interface that allows Consumers to find out the capabilities of
the Producer and about the Portlets it hosts, including the metadata necessary for a
Consumer to properly interact with each Portlet.

•

Markup: A required interface used to request and interact with markup fragments.

•

Registration: An optional interface used to establish a relationship between a Producer
and a Consumer (e.g. for billing or book-keeping purposes).

•
35

Portlet Management: An optional interface that grants access to the life-cycle of thehosted Portlets. This interface also includes Property Management, which enables
programmatic access to a Portlet’s persistent state.

40

In order to allow different levels of sophistication for both the Producer and Consumer, parts ofthis functionality are optional. Various examples of how a Producer might implement particularfunctionality for varying levels of sophistication and with regards to implementing some of theoptional portions of the protocol are contained throughout this document.

45

The Producer optionally manages Consumer registrations. The Producer may require
Consumers to register prior to discovering and interacting with Portlets. A registration
represents a relationship (often including both technical and business aspects) between theConsumer and Producer.

30

Web Services for Remote Portlets Specification

7

1.2.2.1 Portlet Management

5

10

A particular Portlet is identified with a portletHandle. The Consumer uses portletHandles
throughout the communication to address and interact with Portlets via the Producer. The
Portlets a Producer publishes as available for all Consumers to interact with are called“Producer Offered Portlets”. Producer Offered Portlets are pre-configured and not modifiable by
Consumers.
If the Producer chooses to expose the Portlet Management interface, it is allowing Consumers
to clone the Portlets offered by the Producer and customize those cloned Portlets. Such auniquely configured Portlet is called a “Consumer Configured Portlet”. Like Producer Offered
Portlets, a portletHandle is used to address Consumer Configured Portlets. This
portletHandle is both; 1) invariant until released and 2) unique within and scoped to theConsumer registration.

1.2.3 Consumer
15

20

A Consumer is an intermediary system that communicates with presentation-oriented web
services (i.e. Producers and the Portlets they host) on behalf of its users. It gathers andaggregates the markup delivered by the Portlets and presents the aggregation to the End-User.
One typical Consumer is a portal, which mediates the markup and the interaction with thismarkup between End-Users and presentation-oriented web services. Another typical Consumer
is an e-Commerce application that aggregates manufacturer-provided content into its own
pages. Since the Consumer is an intermediary, aggregating system, the markup sent for
display to the End-User and most interactions with that markup flow through the Consumer.
This often results in situations where the End-User implicitly trusts the Consumer to respect
their privacy and security concerns with regards to this information flow.

25

30

While this specification is neutral as to the markup used to represent the user interface to the
End-User, we note that general performance concerns favor markup technologies that push theprocessing of user interface logic, such as the validation of End-User input, as far toward theuser agent as possible. Client-side scripting and XForms2 represent technologies that can beleveraged to address these performance concerns. Note that use of such technologies does
not relieve the need for a Portlet to validate the input data it receives.

1.2.4 End-User
35

The main purpose of a Consumer that aggregates content from various Producers/Portlets isthe preparation and presentation of markup to an End-User. In addition, the Consumer needs
to manage the processing of interactions with that markup in order to properly correlate theinteractions with the, potentially stateful, environment that produced the markup.

1.3 Typical Process Flow
While some of the following steps are optional, the typical flow of interactions between these
actors is:40

1. Consumer “discovers” the Producer. This involves the Consumer learning the URL of
the web service end-point for the Producer and getting the Producer’s metadata with its
description of the registration requirements and possibly an indication of the portlets
the Producer is exposing.

2

http://www.w3.org/TR/xforms/

Web Services for Remote Portlets Specification

8

2. Establishment of a relationship between the Consumer and Producer. This may involvethe exchange of information regarding capabilities, security requirements or otherbusiness and/or technical aspects of the relationship.
5

3. Consumer learning the full capabilities and services of the Producer based on the now
established relationship.
4. Establishment of a relationship between the Consumer and End-User. This permits theConsumer to authenticate the End-User and may allow the End-User to customize theaggregated pages presented by the Consumer.

10

5. Production of aggregated pages. This typically involves the Consumer defining somebase level of page design (often with customized Portlets) and may involve further
customization of those pages by the End-User.
6. Request for a page. This typically results when the End-User directs a user-agent (e.g.
browser) to the Consumer’s URL, but also occurs indirectly as a result of processing aninteraction with the markup of a previous page.

15

20

25

7. Processing interactions. Some End-User interactions with the markup of a page will
result in an invocation on the Consumer to provide some logical function. The
Consumer will process this invocation to determine the Producer/Portlet that theinteraction has targeted and the nature of the invocation requested for that Portlet.
Since the resulting invocation of that Portlet is likely to change its state (and may alsochange the state of other Portlets), the Consumer must also treat this as an indirect
request for a page and thereby loop back to step 6.
8. Destruction of relationships. Producers and Consumers may choose to end aregistration relationship at any time. The protocol provides means by which theProducer and Consumer may inform each other that the relationship (or some portionof it) has ended and that related resources may be cleaned up.

2 Terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD
NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as
described in [RFC2119].
30
Compliance: Mandatory – relevant to legal rules, regulations or laws. Compliancy is the act ofcomplying with a specification and/or standard. Example: ISO 9001. IEEE defines as complying
with laws and regulations.
35

40

Conformance: Not mandatory – ISO/IEC Guide 2 defines conformance or conformity as
fulfillment of a product, process or service of specified requirements.
Cross references to the [Requirements] developed by both the WSIA and WSRP technicalcommittees are designated throughout this specification by a hyperlink to the requirement
contained where the requirement number is enclosed in square brackets (e.g. [A100]).

3 General Considerations
45

The major design goals of this specification are simplicity, extensibility and efficiency. This
specification seeks to accomplish these goals whenever possible by leveraging otherstandards. It also seeks to accomplish these goals in a manner that is neutral as to the platform
any particular actor may be using to participate in interactions governed by this specification.
Web Services for Remote Portlets Specification

93.1 Related Standards
This specification seeks to leverage both existing and emerging web service standards
whenever possible. The following are particularly noted as relevant standardization efforts:

3.1.1 Existing Standards
5

WSDL – Defines how abstract interfaces and their concrete realizations are defined.
Schema – Defines how types are defined and associated with each other.
Namespaces – Defines how XML Namespaces are declared and used.
SOAP – Defines how to invoke web service interfaces.
SSL/TLS – Defines secure transport mechanisms.

10

URL – Defines URI (includes URL) syntax and encoding
Character Sets - Character set encoding
XML Digital Signatures – Defines how portions of an XML document are digitally signed.
SAML – Defines how authentication and authorization information may be exchanged.
XACML – Defines syntax for expressing authorization rules.

15

P3P – Defines how a Producer/Portlet may publish its privacy policy so that a Consumer could
enforce End-User privacy preferences.

3.1.2 Emerging Standards
XML Encryption – Defines how to encrypt/decrypt portions of an XML document.
WS-Security – Defines how document level security standards apply to SOAP messages.
20

RLTC – Defines syntax for expressing authorization rules.
XCBF – Defines how to exchange biometric data.
WS-Attachments - Defines how to encapsulate a SOAP message and zero or more
attachments within a DIME message.

25

WS-I.org - Defines profiles for use of web services standards such that interoperability is
maximized.
DIME – A lightweight, binary message format that encapsulates one or more resources in asingle message construct.
JSR168 – Java Community Process for standardizing a portlet API.

3.2 Foundations
30

35

As a specification that enables aggregating applications to use generic proxy code to easily
integrate compliant web services, the foundations for the specification become critical. The textof this specification uses an IDL-like syntax to describe the interface in a non-normative
manner. The ONLY normative description of the interface itself is contained in the WSDL
referenced by section 14. The textual portion of this specification does not contain normative
statements regarding the exact syntax of XML passed between Consumer and Producer, but it
does contain normative statements about the manner and order in which calls must be made inorder to be conformant. The chapters below are organized along the lines of the portTypes
defined in the WSDL and the IDL descriptions of the data types reflect the normative schema
definitions from the WSDL.

Web Services for Remote Portlets Specification10

3.3 Data Objects

510

It is often necessary to pass data to operations. Typed data objects are defined as the transportmechanism wherever possible. The schema definitions of these structures includes the <anynamespace=”##other”/> construct as a standard means for data extensions.
Producers/Portlets employing these extensions are encouraged to provide typing information
for the extended data items [A505]. The preferred means for this typing information includes
using the schema defined3 “type” attribute to reference the correct schema on each suchextension element, and use of either the Producer’s WSDL (default) or a “schemaLocation”
attribute as per standard schema usage to declare the details of all non-simple types. This
allows Consumers to provide type checking outside of that done by typical interface layers.
This specification introduces various data structures as they are needed for operations and has
a list of all these data structures in Appendix C.

3.4 Lifecycles
15“Lifecycle” is a term used to describe how items become available, are interacted with, andfinally are destroyed. The two lifecycles included in this specification are:
Persistent: This lifecycle starts with an explicit operation to create the item and ends only withan explicit operation to destroy the item. Examples include the registrationHandle andConsumer Configured Portlets.

20

Transient: This lifecycle can either start with an explicit operation OR as a side effect of someother operation [A204]. The item created is transient and no explicit operation is required todestroy it. This specification generally includes an expires element when a transient item iscreated so that any resources at the Consumer related to the item may be reclaimed at an
appropriate time. An example of this is session creation.

3.5 Scopes
25

30

35

40

Scope is a term used to describe when something is valid. An item often scopes both theusage and lifecycle of other items. Scopes that are referenced in this specification are:
Registration scope: This scope is initiated when a Consumer registers with a Producer andends when the handle referring to that registration is released. As such it encompasses any
Portlets the Consumer configures and any interactions with the Portlets of the Producer. From
the Producer’s perspective, this scope has a persistent lifecycle. This scope is referenced
throughout the protocol using a registrationHandle. The registrationHandle is created
and destroyed using either in band mechanism, i.e. by declaring support for the Registration
portType, or by out of band mechanism, whereby the registrationHandle is created anddestroyed by means outside this specification.
Portlet scope: This scope is initiated for a Producer Offered Portlet when the portlet is added
to the set returned in the metadata of the Producer. This scope is initiated for a Consumer
Configured Portlet when the Portlet is cloned and as such will be encapsulated by a registration
scope. This scope ends for Consumer Configured Portlets when the reference to the Portlet is
explicitly released. As such it encompasses all interactions with the Portlet. This scope has apersistent lifecycle and is referenced using a portletHandle. The Producer optionally exposes
this scope by declaring support for the PortletManagement portType. If the Producer exposes
the PortletManagement portType, then the Consumer can clone the Producer Offered Portlets
and uniquely configure them for its own use. The Consumer can also choose to directly use theProducer Offered Portlets.

3

http://www.w3.org/TR/xmlschema-1/#xsi_type

Web Services for Remote Portlets Specification11

5

Session scope: This scope is initiated when a Portlet needs to store transient state on the
Producer and is always encapsulated by the Portlet’s scope. This scope ends when thesession holding that state is released (either via an explicit operation on the Producer OR via atimeout mechanism). As such it encompasses a set of operation invocations in which theConsumer has supplied the session handle. This scope has a transient lifecycle and isestablished by the Producer returning a new SessionContext. The Consumer MUST respect
this new session scope as described in section 6.1.1.

3.6 Types of Stateful Information
10

15

20

Because the WSRP protocol operates over connectionless technologies, the Producer must beable to return information to the Consumer, with the understanding that this information will besent back to it [A200]. Three types of stateful information exist:
Navigational state: This is the state that allows the current page fragment to be correctly
generated multiple times. Web applications typically store this type of state in the URL so thatboth page refresh and bookmarked pages will generate what the End-User expects. The
Producer returns this state to the Consumer as navigationalState such that it may satisfy
these expectations of the End-User. To supply the bookmarking and page refresh capabilities
End-Users expect, the Consumer MAY store this state, or a reference to it, in the URL.
Transient state: This is state that applies to a restricted set of operations. This specification
defines two kinds of transient state; namely:
Interaction State: This state is supplied to the processing of an interaction with a
Portlet’s markup and is often used as the equivalent of input parameters to thatprocessing.

25

30

35

40

Session State: This state is stored on the Producer and is related to a sequence of
operations (for example, an e-Commerce site may store a shopping cart in its transientstate). Once a session is generated, the Producer returns a reference to it and theConsumer must return this reference on future invocations as described in section 6.1.2.
This type of state will be referred to as a Session (similar to an HTTP Session) and an
opaque reference to one is a sessionID.
Persistent state: This is state that is persisted until either the Consumer or Producer explicitly
discards it. This specification defines two kinds of persistent state with each referred to via ahandle that MUST remain invariant once the Producer supplies it to the Consumer:
Consumer Registration: Represents a relationship between a Consumer and Producer(also a registration scope). Data that is part of the Consumer registration state impacts all
invocations within the scope of the registration. The opaque reference to Consumer
registration state is referred to as a registrationHandle.
Portlet: In addition to the Portlets a Producer offers for all Consumers to use, the abilityof a Consumer to create a unique configuration of one of those Portlets for its own use isdefined. The opaque reference to a configured Portlet is referred to as a portletHandle(also correlates to a Portlet scope).

3.7 Persistence and statefulness

45

This specification does not mandate that either the Producer or the Consumer is stateful[A201]. In the getMarkup() and performBlockingInteraction() calls, the navigationalState
field carries the state necessary for the Portlet to render the current markup to be returned to
the Consumer. This enables the Consumer to reasonably support page refresh andbookmarking by the End-User. If the Producer utilizes local state, storing this state in an
implementation-dependent manner, then it will return a sessionID to the Consumer for use
during the lifetime of the session.

Web Services for Remote Portlets Specification12

5

If the Consumer is operating in a stateless manner, then it may choose the way to achieve this.
In the case of HTTP transport the Consumer may employ standard HTTP mechanisms(cookies or URL-rewriting) to propagate the navigational state or sessionID out to its client. If
operating in a stateful manner, the Consumer may employ any number of persistence/cachingmechanisms [A202].

10

The nature of the conversation between the client and the Consumer, for purposes of thissection, is out of scope [A304]. This does not mean that information about the client, including
user profile data, is opaque to the Producer. There are many use cases for which user identity
must be conveyed to the Producer [A501][A606].

3.8 Producer Mediated Sharing

15

Producers may implement a sharing mechanism through techniques such as a shared area
within sessions for Portlets to use. The Producer indicates which Portlets share such data
areas via the groupID parameter in the Portlet metadata. Section 5.1.18 specifies how theConsumer is to process Producer's grouping, which are defined by the groupID parameters.

20

Shared data areas introduce implementation challenges in clustered environments. In such anenvironment, multiple concurrent requests may be routed to different cluster nodes. The
Producer must ensure that Portlets with a common shared data area have access to the shareddata even in such situations.

3.9 Information Passing Mechanisms
All information passing enabled by this specification is between exactly one Producer and one
Consumer. Implementation of data sharing, including both policy and side effects, within aparticular Producer service is outside the scope of this specification.
25

3.10 Two-step protocol

30

This specification attempts to account for both isolated interactions between a Consumer and a
Producer, and also those interactions that may cause state changes in other Portlets theConsumer aggregates from the same Producer [A503]. Common causes of such shared stateinclude use of a common backend system (e.g. database) and Producer-mediated data
sharing. For these reasons, there is a “two-step” capability built into the protocol.

35

40

In this two-step interaction, the Consumer first invokes performBlockingInteraction() on the
Portlet whose markup the End-User interacted with. The Consumer MUST NOT invoke
operations on any Portlets within the context of the initiating request from the client of theConsumer until either the receipt of a response or the invocation of
performBlockingInteraction() fails (e.g. times out). The Consumer then invokes getMarkup()on the Portlets being aggregated.
Interaction semantics are well-defined across the spectrum of interaction styles supported in
the protocol. In other words, the results of the Consumer invoking
performBlockingInteraction() on a Portlet, regardless of whether the interaction may haveside effects on other Portlets at the Producer, is well-defined independent of the order of
getMarkup() invocations on the Portlets.

Web Services for Remote Portlets Specification

13

3.11 Transport Issues

5

10

Since the transport layer is often used to store various pieces of information (e.g. J2EE loadbalancing depends on a session cookie and HTTP transport), and these pieces of information
often will pertain to a client session with the Consumer rather than the Consumer itself,
Consumers that manage transport layer issues, such as cookies, MUST return them to the
Producer only for subsequent invocations within the Markup Interface during the same client
session. In addition, any supplying of cookies to resources the portlet references needs to be inconformance with the rules established by RFC21094. Not scoping their return in this manner
will likely result in a loss of privacy for the End-User and unexpected behavior in general.
Failure to return them for this full duration will often result in a loss of state at the Producer andunexpected behavior for the End-User. We also note that failure to properly do thismanagement will eliminate the ability to use Producers that set requiresInitCookie to avalue other than “none”.

3.12 Load Balancing
15

20

Load balancing is a part of the Producer environment that cannot easily be managed fromwithin the protocol. Load balancing is highly dependent on mechanisms in the transport, forexample the use of cookies in HTTP. In order to permit load balancing to function, regardlessof the transport binding in use, the Consumer needs to manage transport level issues itself.
Using HTTP as an example, if the Producer requires such support of Consumers, it MUST
indicate so by setting the requiresInitCookie metadata to a value other than “none”. If the
Producer set requiresInitCookie to a value other than “none”, the Consumer MUST ensurethat cookies are properly supplied in subsequent requests for the End-User.

4 Interface Overview
This specification defines four interfaces whose operations have the following signatures:
25

4.1 Service Description Operations
The Service Description interface, a required interface, defines an operation for acquiring the
Producer’s metadata.
ServiceDescription = getServiceDescription(RegistrationContext, desiredLocales);

4.2 Markup Operations
30

The Markup interface, a required interface, defines operations for getting the markup from a
Portlet as well as processing user interactions with that markup. This interface also contains
the operation for Consumer assistance in pre-initializing HTTP cookies. Having this operation inthis interface avoids the problems associated with moving cookies between bindings.
MarkupResponse = getMarkup(RegistrationContext, PortletContext, RuntimeContext,
UserContext, MarkupParams);

35

BlockingInteractionResponse = performBlockingInteraction(RegistrationContext,
PortletContext, RuntimeContext, UserContext,
MarkupParams, InteractionParams);

40
4

http://www.ietf.org/rfc/rfc2109.txt

Web Services for Remote Portlets Specification

14

ReturnAny = initCookie(RegistrationContext);

ReturnAny = releaseSessions(RegistrationContext, sessionIDs);

4.3 Registration Operations
5

The Registration interface, an optional interface, defines operations for establishing, updating
and destroying a registration. Each registration reflects a particular relationship between a
Consumer and a Producer.
RegistrationContext = register(RegistrationData);

10

RegistrationState = modifyRegistration(RegistrationContext, RegistrationData);

ReturnAny = deregister(RegistrationContext);

4.4 Portlet Management Operations
15

The Portlet Management interface, an optional interface, defines operations for getting Portlet
metadata, cloning Portlets for further customization and interacting with the property interface.
PortletDescriptionResponse = getPortletDescription(RegistrationContext, PortletContext,
UserContext, desiredLocales);PortletContext = clonePortlet(RegistrationContext, PortletContext, UserContext);

20
DestroyPortletsResponse = destroyPortlets(RegistrationContext, portletHandles);PortletContext = setPortletProperties(RegistrationContext, PortletContext, UserContext,
PropertyList);25
PropertyList = getPortletProperties(RegistrationContext, PortletContext, UserContext,
names);

30

PortletPropertiesDescriptionResponse = getPortletPropertyDescription(RegistrationContext,
PortletContext, UserContext,
desiredLocales);Web Services for Remote Portlets Specification15

5 Service Description Interface
5

A Producer may be discovered through mechanisms such as [UDDI] or [WSIL], which also
provide information concerning the capabilities of the service. Other discovery mechanisms(e.g. emailed URL to a properly enabled user-agent) do not expose these capabilities. The
getServiceDescription() operation provides a discovery mechanism-agnostic means for a
Consumer to ascertain a Producer’s or Portlet’s capabilities [A110]. This interface is required of
all Producers to provide a well-defined means for Consumers to ascertain the requirements toregister or use the Producer.

5.1 Data Structures
10

The normative definitions for all data structures are contained in the WSDL referenced in
section 14. For the convenience of the reader, this non-normative section uses an IDL likesyntax to describe these structures, where the leading [R] indicates a field is required and [O]indicates it is optional. The operations in this section introduce the following data structures:

5.1.1 Extension Type
15

20

25

The Extension structure contains the payload extension mechanism for vendor and application
extensions. This allows arbitrary elements from other namespaces to be sent as part ofcontaining data structures. They are designed to communicate extended information between
the Consumer and Producer. Consumers and Producers SHOULD NOT rely on receiving backany extensions passed to or returned from an invocation. Each such extension MUST declare
its type using the schema-defined “type” attribute5. We RECOMMEND extensions either be oftype xsd:string (where xsd stands for http://www.w3c.org/2001/XMLSchema) or be of a typedefined in the Producer’s WSDL as this enables Consumers to prepare an appropriate
serializer/deserializer. We expect many extensions will be of the type NamedString andencourage its reuse in this manner. The other option is for each message to connect theextension to a type declared in a schema using the “schemaLocation” attribute as used byschema. Consumers and Producers are NOT REQUIRED to process information supplied
using these extension elements.
Extension[O] Object any[]

30

Members:•

any: This field has a schema declaration that allows any elements from namespaces
other than WSRP.

5.1.2 Handle Type
Handles are opaque references that are passed between the Consumer and Producer.
35

40

Handles are represented as restricted strings in the protocol. Although a string is principally
unlimited in length, the length of the handle is restricted for the following reasons:•Handles may be stored in databases and may be used for indexing.

•

The Consumer will likely embed handles in client URLs.

•

Comparison of handles should be efficient.

The maximum length of a handle is restricted to 255 characters. We STRONGLY
RECOMMEND these characters be chosen from the first 127 characters of the Unicodecharacter set, so that the length is no longer than 255 characters regardless of whether it is5

http://www.w3.org/TR/xmlschema-1/#xsi_type

Web Services for Remote Portlets Specification

16

represented in Unicode, ASCII or a byte[]. Not following this recommendation will likely cause
information to be lost as the Consumer stores and retrieves the value. The Consumer MAY
truncate longer handles to 255 characters.
Handle extends string (maximum length = 255)

510

5.1.3 Key TypeKeys are similar to Handles except that they are not opaque references. They are used for
keying data and therefore need to support efficient comparisons. As a result their length isrestricted to 255 characters. We STRONGLY RECOMMEND these characters be chosen fromthe first 127 characters of the Unicode character set, so that the length is no longer than 255
characters regardless of whether it is represented in Unicode, ASCII or a byte[]. Not following
this recommendation will likely cause information to be lost as the value is stored and retrieved.
Key extends string (maximum length = 255)

5.1.4 ID Type15

20

IDs are used to refer to something, but are unlikely to be used as keys. As a result the length
restriction is relaxed to 4096 characters. We STRONGLY RECOMMEND these characters bechosen from the first 127 characters of the Unicode character set, so that the length is nolonger than 4096 characters regardless of whether it is represented in Unicode, ASCII or abyte[]. Not following this recommendation will likely cause information to be lost as the value isstored and retrieved. Those originating an ID are encouraged to keep them as small as
possible relative to impacts on the other party’s performance when storing large numbers ofthese (e.g. a sessionID is per user per Portlet and therefore a Consumer is likely to store a verylarge number of them).
ID extends string (maximum length = 4096)

5.1.5 LocalizedString Type
25

This LocalizedString structure describes both the value for a particular locale and theresource name that can be used to extract the value for other locales from a ResourceList.
LocalizedString[R] string xmlLang[R] string value[O] string resourceName

30

Members:35•

xmlLang: The locale for this supplied localized value. This is carried in the WSDL
using the xml:lang attribute.

•value: The value for this localized string in the declared locale.

•resourceName: The name assigned to this localized string for dereferencing into a
ResourceList for values from other locales. When the resourceName is not supplied,there are no values for additional locales available in the ResourceList.

Web Services for Remote Portlets Specification

17

5.1.6 ResourceValue Type
This structure provides the value of a resource for a locale.
ResourceValue[R] string[R] string[O] Extension

5

xmlLangvalue
extensions[]

Members:10•

xmlLang: The locale for this localized value. This is carried in the WSDL using thexml:lang attribute.

•value: The value for this localized string in the declared locale.

•extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

5.1.7 Resource TypeThe Resource structure carries the values for a resource in a set of locales.
15

Resource[R] string
resourceName[R] ResourceValue values[][O] Extension
extensions[]

Members:20•

resourceName: The name of the resource for which this is a list of localized values.

•

values: Each member of this array provides the value for the resource in a locale.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.8 ResourceList Type
25

This is an array of Resource structure, each of which carries the values for a localized resourcein various locales.
ResourceList[R] Resource[O] Extension

30

resources[]
extensions[]

Members:•resources: Each member of this array provides the localized values for a resource.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.9 ItemDescription Type
3540This structure is used to describe custom items a Consumer is allowed to use when interactingwith the Portlets at the Producer.
ItemDescription[R] string
itemName[R] LocalizedString description[O] Extension
extensions[]

Web Services for Remote Portlets Specification

18

Members:•

itemName: The name for this item. The preferred form is a URI such that it isdefinitively namespaced.

•description: A localized, free form description of the item. Expected use of this field
is for display at the Consumer to someone who will provide a mapping to Consumer
information.

•

extensions: The extensions field MAY be used to extend this structure. Extension

5

elements MUST be from namespaces other than WSRP.

5.1.10 MarkupType Type
10The MarkupType data structure is used to carry Portlet metadata that is mime type specific.
MarkupType[R] string[R] string[R] string[O] string[O] Extension

15

mimeTypemodes[]
windowStates[]
locales[]
extensions[]

Members:•

mimeType: A mime type supported by the Portlet (e.g. text/html, application/xhtml+xml,
text/vnd.wap.wml) for which the remainder of this structure applies. In addition to thesefully specified mime types, use of “*” (indicates all mime types are supported) andtype/* (where type includes things such as “text”) from the HTTP definition6 MAY be
specified. The Consumer does not have to process any optional parameters that canbe included on mime type declarations.

•modes: The modes (defined in section 6.8) that are supported by the Portlet for thismimeType.

20

25

Possible values are:•those defined by this specification in section 6.8;•

modes supplied by the Consumer in consumerModes;•

any custom modes the Producer wishes to advertise as valid (see section
6.8.5).

30

Localized descriptions are only needed for the last category since the first two do not
require manual interpretation.
•
35

windowStates: The windowStates (defined in section 6.9) that are supported by thePortlet for this mimeType.

Possible values are:40•

those defined by this specification in section 6.9;•

window states supplied by the Consumer in consumerWindowStates;•

any custom window states the Producer wishes to advertise as valid (seesection 6.9.5).

Localized descriptions are only needed for the last category since the first two do not
require manual interpretation.

6

http://www.ietf.org/rfc/rfc2616.txt

Web Services for Remote Portlets Specification19

•

locales: An optional array of locales for which this mimeType is available (e.g. “en-US”).
If this array is not supplied, the Consumer can assume the Portlet will attempt togenerate markup for any requested locale. Note that current practice on the Internet
uses the format [2 char language code]7 “-” [2 char country code]8 as per the provided
example. Values only using a two character language code mean that the Portlet iswilling to generate markup of this type for any locale starting with the specified
language code.

•

extensions: The extensions field MAY be used to extend this structure. Extension

5

elements MUST be from namespaces other than WSRP.

10

5.1.11 PortletDescription TypeThe PortletDescription structure contains a set of fields that provide the metadata to
describe the Portlet as well as any clones of the Portlet.
PortletDescription[R] Handle
portletHandle[R] MarkupTypemarkupTypes[][O] ID
groupID[O] LocalizedString description[O] LocalizedString shortTitle[O] LocalizedString title[O] LocalizedString displayName[O] LocalizedString keywords[][O] string
userCategories[][O] string
userProfileItems[][O] boolean
usesMethodGet[O] boolean
defaultMarkupSecure[O] boolean
onlySecure[O] boolean
userContextStoredInSession[O] boolean
templatesStoredInSession[O] boolean
hasUserSpecificState[O] boolean
doesUrlTemplateProcessing[O] Extension
extensions[]

15

20

25

30

Members:•

portletHandle: The handle by which Consumers can refer to this Portlet. Note thatHandles are restricted to a maximum length of 255 characters.

35

40

•

markupTypes: Each member of this array specifies metadata for a single mimeType.

•groupID: Identifier for the group within which the Producer places this Portlet or any
Portlets derived from it via the cloning process.

•description: Localized descriptions of the Portlet. This is intended for display inselection dialogs, etc.

•

shortTitle: Localized short title for the Portlet.

•

title: Localized title for the Portlet. This value is intended for display in a titlebar

decoration for the Portlet’s markup.

•

displayName: Localized value intended for display in a Consumer’s tooling for building

aggregated page. In general this value is shorter than either title, though the available
title values can be used as a default if this value is missing.

45

7
8

http://lcweb.loc.gov/standards/iso639-2/langcodes.html
http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html

Web Services for Remote Portlets Specification

20

•

keywords: Array of localized keywords describing the Portlet which can be used forsearch, etc.

•

userCategories: Array of category names for the Producer’s user categories that thePortlet supports. Each of these user categories has to have a ItemDescription
available to the Consumer through the Producer’s ServiceDescription. [R416]•

userProfileItems: An array of strings that enumerate what portions of the
UserContext structure the Portlet needs to provide full functionality. For the fields this5

specification defines, the named profile items a Portlet uses MUST all come from the“Profile Name” column of the table found in section 11. Any use of additional
userProfile items specified as available when the Consumer registered SHOULD use
the names the Consumer supplied. Any additional items specified SHOULD beinterpreted by the Consumer as additional items the Portlet could use if the Consumer
is able to supply the data.

10

•
15

usesMethodGet: A flag indicating the Portlet generates markup that uses method=get
in an HTML form. If the Consumer uses a Portlet which specifies usesMethodGet as”true”, the Consumer MUST format its URLs in a manner that keeps user-agents fromthrowing away information (see section 10.2.4 for a description of the difficulties inusing forms with method=get). The default value of this flag is “false”.

•

defaultMarkupSecure: Flag that indicates whether this Portlet requires securecommunication on its default markup. This flag applies to all markup not generated asa direct result of an End-User interaction. The default value for this flag is “false”.

•

onlySecure: Flag that indicates whether this Portlet requires secure communicationon all its markup. The intent of this flag is to allow Consumers to treat the Portlet
specially because of this characteristic. The default value for this flag is “false”.

•

userContextStoredInSession: A flag indicating the Portlet will store any supplied
UserContext in the current session. Setting this flag to “true” allows the Consumer to
optimize when the UserContext is included on operation invocations. Since some datain the UserContext is sensitive, many Consumers will require that secure

2025communication be used when the information is passed. Not requiring this of all
invocations can result in a significant performance difference. Note that the Consumer
MAY send UserContext information on any invocations as a replacement for
information the Portlet MAY be storing in a session. The default value of this flag is“false”.

30•
35

significant performance difference. Note that the Consumer MAY send templates on
any invocations as a replacement for information the Portlet MAY be storing in asession. The default value of this flag is “false”.

40

45

50

templatesStoredInSession: A flag indicating the Portlet will store any supplied
templates in the current session. Setting this flag to “true” allows the Consumer to
optimize when the templates structure is set in MarkupParams. Since the content of
the templates structure can get quite large, not requiring it to be passed can result in a•

hasUserSpecificState: A flag indicating the Portlet will store persistent state specificto each End-User. Setting this flag to “true” suggests to the Consumer to clone thePortlet when placing it on an aggregated page rather than waiting for the processing
described in section 6.3.2. The default value of this flag is “false”.

•

doesUrlTemplateProcessing: A flag indicating the Portlet will process any
templates supplied so as to correctly write URLs in its markup. For Portlets setting
doesUrlTemplateProcessing to “true”, Consumers MUST provide the URL writing
templates and namespacePrefix field. The default value of this flag is “false”.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification

21

5.1.12 Property TypeThe Property data structure is used to carry typed information between the Consumer and theProducer.
Property[R] string name[O] string xmlLang[O] Object value[]

5

Members:10•

name: Name of the property, MUST have a non-zero length.

•

xmlLang: The locale for the supplied localized value. This is carried in the WSDL using
the xml:lang attribute.

•value: The property’s value. The type information needed to properly serialize /deserialize this value is carried in the relevant PropertyDescription. Note that the
WSDL from section 14 defines two means by which this field may be sent, either as a
generic array of elements or as a single element with a type of string. This second
choice was added as many properties are likely to be of this type and it allows the web
stack to automatically do the (de)serializing to the wire format.

15

5.1.13 ResetProperty Type
20

The ResetProperty data structure carries the name of a Property for which the Consumer
wants the value reset to the default.
ResetProperty[R] string

nameMembers:•25

name: Name of the property whose value is to be reset; MUST have a non-zero length.

5.1.14 PropertyList TypeA PropertyList gathers a set of Property structures together for transmitting between theConsumer and Producer.
PropertyList[O] Property
properties[][O] ResetProperty resetProperties[][O] Extension
extensions[]

30

Members:•

properties: Each member in this array is a Property structure carrying information

concerning one property.

35•

resetProperties: Each member in this array is a ResetProperty structure carrying aproperty to reset to its default value.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

40

It is an error for a property to be referenced by both the properties and resetProperties
arrays. The Producer MUST return an Interface.InvalidParameters fault message if theConsumer supplies a property in both the properties and resetProperties array of a
PropertyList.

Web Services for Remote Portlets Specification

22

5.1.15 PropertyDescription Type
Each property of a Portlet is described using the following structure.
PropertyDescription[R] string
name[R] QName
type[O] LocalizedString label[O] LocalizedString hint
[O] Extension
extensions[]

5

Members:10•

name: Name of the property being described, MUST have a non-zero length.

•

type: Type of the property. For those not familiar with the QName type, we note that

this is a namespace qualified name. We would encourage these to either be from theset of schema-defined types or be explicitly typed in the schema element of an
enclosing ModelDescription. This allows the Consumers to prepare the appropriate
serializer/deserializer. The namespace for the schema-defined types used by thisspecification is http://www.w3c.org/2001/XMLSchema. Producers can assume that all
Consumers support the basic types defined by http://www.w3c.org/TR/xmlschema-2/.

15•label: A short, human-readable name for the property. Intended purpose is for display

in any Consumer-generated user interface for administering the Portlet.

20•

hint: A relatively short description of the property. Intended for display, for example,

as a tooltip in any Consumer-generated user interface for editing the property.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.16 ModelTypes Type25

The ModelTypes structure contains the payload mechanism for declaring the types referenced
by the PropertyDescriptions of a ModelDescription.
ModelTypes[R] Object any[]

Members:30•

any: This field has a schema declaration that allows any elements from the schema

namespace.

5.1.17 ModelDescription TypeThe set of properties of a Portlet are described in its metadata using the following structure.
ModelDescription[O] PropertyDescription[O] ModelTypes[O] Extension

35

propertyDescriptions[]
modelTypes
extensions[]

Members:
40•

propertyDescriptions: Array of property descriptions.

•modelTypes: A container for type definitions for the properties of this model. It is

expected that XML schema will commonly be used to define Portlet-specific datatypes
referenced in the propertyDescriptions.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification23

5.1.18 CookieProtocol Type
This type is a restriction on the string type that is constrained to the values “none”, “perUser” or“perGroup”. These values carry the following semantics:
5•”none”: The Producer does not need the Consumer to ever invoke initCookie().

•”perUser”: The Consumer MUST invoke initCookie() once per user of the Consumer,
and associate any returned cookies with subsequent invocations on behalf of that user.

•”perGroup”: The Consumer MUST invoke initCookie() once per unique groupID fromthe PortletDescriptions for the Portlets it is aggregating on a page for each user of
the Consumer, and associate any returned cookies with subsequent invocations onbehalf of that user targeting Portlets with identical groupIDs.

10

5.1.19 ServiceDescription TypeThe ServiceDescription structure contains a set of fields that describe the offered services of
the Producer.
15

ServiceDescription[R] boolean[O] PortletDescription[O] ItemDescription[O] ItemDescription[O] ItemDescription[O] ItemDescription[O] CookieProtocol[O] ModelDescription[O] string[O] ResourceList[O] Extension

20

25

requiresRegistration
offeredPortlets[]
userCategoryDescriptions[]
customUserProfileItemDescriptions[]
customWindowStateDescriptions[]
customModeDescriptions[]
requiresInitCookie
registrationPropertyDescription
locales[]resourceList
extensions[]

Members:•

requiresRegistration: A boolean indicating whether or not the Producer requires
Consumer registration. If requiresRegistration is set to “false” then it MUST be
valid to not pass a RegistrationContext parameter to all operations with thisparameter. If requiresRegistration is set to “true” then the Producer MUST return afault message when no RegistrationContext is supplied to an operation, other than
getServiceDescription(), which takes this field.

•

offeredPortlets: An array of structures (defined in Section 5.1.11) containing themetadata for the Producer Offered Portlets.

•

userCategoryDescriptions: An array of ItemDescription structures as defined in
Section 5.1.9. This array includes entries for every user category the Producer is willingto have the Consumer assert for an End-User, including the user category names
defined in section 1B.1 of this specification. Note that user categories are Producerwide and therefore are inherently shared by the Producer’s Portlets.

•

customUserProfileItemDescriptions: An array of ItemDescription structures as
defined in Section 5.1.9. This array MUST include an entry for any user profile item theProducer supports which is not defined by this specification.

•customWindowStateDescriptions: An array of ItemDescription structures as
defined in Section 5.1.9. This array MUST include an entry for any custom window
state the Producer supports.

30

35

40

45

Web Services for Remote Portlets Specification24

•customModeDescriptions: An array of ItemDescription structures as defined in
Section 5.1.9. This array MUST include an entry for any custom mode the Producer
supports.

•

requiresInitCookie: A string (default value = “none“) indicating whether or not theProducer requires the Consumer to assist with cookie support of the HTTP protocol.

•

registrationPropertyDescription: Property descriptions for information the5Consumer needs to supply during registration.

•
10

locales: This array is a superset of locales for which the localized strings of thisserviceDescription can be requested. The existence of a locale in this array does
not imply that all fields of the ServiceDescription are available in the locale. Notethat this is independent of the locales for which any of the portlets of this Producer
might supply markup.

15•

resourceList: This is an array of Resource structures, each of which carries thevalues for a localized resource in various locales.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.20 RegistrationState Type
20

The RegistrationState structure contains fields related to a particular registration of a
Consumer with a Producer. It is returned by the modifyRegistration() operation and contains
the fields of a RegistrationContext that allow a Producer to push the storage of state atregistration scope to the Consumer.
RegistrationState[O] base64Binary[O] Extension

25

30

registrationState
extensions[]

Members:•

registrationState: This field is used only when the Producer wants the Consumer
to provide persistent storage for the state resulting from processing the registration. If
the RegistrationState field has a value, the Consumer MUST return this value on
any subsequent calls in the context of this registration [R362].

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.21 RegistrationContext Type35

The RegistrationContext structure contains fields related to a particular registration of a
Consumer with a Producer. It is returned by the register() operation and is a required
parameter on most other operations.
RegistrationContext[R] Handle[O] base64Binary[O] Extension

40

registrationHandle
registrationState
extensions[]

Members:•

registrationHandle: An unique, invariant and opaque reference to the Consumer-

Producer relationship. This reference is generated by either the register() operation[R355] or a process outside the scope of this specification. Note that Handles are
restricted to a maximum length of 255 characters.

Web Services for Remote Portlets Specification

25

5

•

registrationState: This field is used only when the Producer wants the Consumer
to provide persistent storage for the state resulting from processing the registration. If
the RegistrationState field has a value, the Consumer MUST return this value on
any subsequent calls in the context of this registration [R362].

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5.1.22 desiredLocales
1015This parameter is used to control the locales for which localized strings are returned. The
desiredLocales parameter is an array of strings, each of which specifies a single locale,whose order indicates the preference of the Consumer as to the locales for which values are
returned. Since localized strings use an indirection through resources to carry the set of values
for different locales, the first member of this array SHOULD be used as the locale for the values
returned directly in the structure. When no desiredLocales array is supplied, the Consumer isrequesting values for all returned localized strings in all locales where they are available. Since
excessive amounts of data can impact both network transmission times and processing time at
the Consumer, Producers are encouraged to only send the localized data the Consumer
actually requests.

5.2 getServiceDescription() Operation
20

This operation allows a Producer to provide information about its capabilities in a contextsensitive manner (e.g. registration may be required to discover the full capabilities of a
Producer) [R303].
ServiceDescription = getServiceDescription(RegistrationContext, desiredLocales);Faults: Security.InvalidRegistration, Interface.OperationFailed

25

30

Producers may choose to restrict the information returned in serviceDescription based on
the supplied RegistrationContext. The minimum information a Producer MUST return from
getServiceDescription() is that which declares what is required for a Consumer to register (i.e.
the requiresRegistration flag and the registrationPropertyDescription field) with theProducer [R300][R301][R303]. Note that the RegistrationContext parameter is not likely tobe supplied when an unregistered Consumer invokes getServiceDescription(). This allows theConsumer to gain access to the information required to successfully register. It is
recommended that Consumers invoke getServiceDescription() after registering in order toreceive a full description of the capabilities the Producer offers within the context of that
registration. Producers MUST return a complete enough ServiceDescription to registered
Consumers for them to properly interact with both the Producer and Portlets it exposes.

35
When generating the ServiceDescription response the Producer SHOULD use thedesiredLocales (an array of strings) to control what locales are returned for localized strings.

40

While it is possible a ServiceDescription will change with time (e.g. Producer deploys
additional Portlets), Producers are encouraged to return as complete a ServiceDescription
as possible.

Web Services for Remote Portlets Specification

26

6 Markup Interface
5

As interactive presentation-oriented web services, all WSIA or WSRP compliant services
implement the markup interface. This interface has operations to request the generation of
markup and the processing of interactions with that markup [A300]. This section explains boththe signatures for these operations and how the concepts of mode and window state impact thegeneration of the markup.

6.1 Data Structures
10

The normative definitions for all data structures are contained in the WSDL referenced in
section 14. For the convenience of the reader, this non-normative section uses an IDL likesyntax to describe these structures, where the leading [R] indicates a field is required and [O]indicates it is optional. The operations in this section introduce the following data structures:

6.1.1 SessionContext TypeThe SessionContext structure contains the ID and expires information the Consumer needs
to refer to the session in subsequent invocations.
15

SessionContext[R] ID[R] int[O] Extension

sessionID
expires
extensions[]

Members:20•

sessionID: An opaque string the Portlet defines for referencing state that is stored

locally on the Producer. If the Consumer fails to return this reference on future
invocations, the Portlet will be unable to reference this state and therefore likely not
generate a markup fragment meeting the End-User’s expectations. The maximum
length of a sessionID is 4096 characters, though Producers SHOULD keep it as short
as possible as this can have a significant impact on Consumer performance. Producers
SHOULD also keep the sessionID as stable as possible since changes in value canalso have a significant impact on Consumer performance.

25•

expires: Maximum number of seconds between invocations referencing thesessionID before the Producer will schedule releasing the related resources. A valueof –1 indicates that the sessionID will never expire.

•

extensions: The extensions field MAY be used to extend this structure. Extension

30

elements MUST be from namespaces other than WSRP.

35

If the Producer returns an Interface.InvalidSession fault message after returning asessionID, the Consumer MUST NOT resupply that sessionID on a subsequent invocationand SHOULD reinvoke the operation that caused the fault message without any sessionIDand supply any data that may have been stored in the session.

6.1.2 RuntimeContext TypeThe RuntimeContext structure defines a collection of fields used only in transient interactions
between the Producer and Consumer.
40

45

RuntimeContext[R] string[O] Key[O] string[O] Templates[O] ID

userAuthentication
portletInstanceKey
namespacePrefix
templates
sessionID

Web Services for Remote Portlets Specification

27

[O] Extension

extensions[]

Members:•

userAuthentication: String indicating how the End-User was authenticated.
Common values include:5o “wsrp:none”: No authentication was done, user information is asserted for
informational purposes only.
o “wsrp:password”: The End-User identified themselves using the common
userid/password scenario.
o “wsrp:certificate”: The End-User presented a security certificate to validate
their identity.

10o Other strings: Some authentication was done outside this limited set of
possibilities.
•

which the Consumer MAY supply as a reference to its use of the Portlet. The intent of
this reference is to allow the Portlet, whenever needed, to namespace multiple
instances of itself in an optimal manner. Examples include within any Producer-defined
data sharing mechanisms and multiple inclusions on a Consumer page. Since thisreference is a Key, its length is restricted to 255 characters. Consumer SHOULD keep
their portletInstanceKey values as short as possible.

15

20

portletInstanceKey: An opaque string, unique within the RegistrationContext,•

namespacePrefix: This field provides a useful string for the Portlet prefixing of tokens

that need to be unique on the aggregated page (e.g. JavaScript variables, html id
attributes, etc.).

•

templates: If this Portlet declared doesUrlTemplateProcessing as “true” in its
PortletDescription, then this field contains the templates the Consumer is supplying
for that processing. If the PortletDescription also has templatesStoredInSession
set to “true”, then the Consumer MAY elect to only send these once for a sessionID.

•

sessionID: An opaque string the Producer defines for referencing state stored locally25on the Producer. If the Producer has returned such a reference and the Consumer fails
to return it in this field on future invocations, the Portlet will be unable to reference thisstate and therefore likely not generate a markup fragment meeting the End-User’s
expectations.

30•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.3 PortletContext Type35

The PortletContext structure is used as a parameter on many operations to supply thePortlet information that was pushed to the Consumer.
PortletContext[R] Handle[O] base64Binary[O] Extension

40

portletHandle
portletState
extensions[]

Members:•

portletHandle: An opaque and invariant handle, unique within the context of theConsumer’s registration (unique within the Producer for Producers not supporting
registration). Note that Handles are restricted to a maximum length of 255 characters.

Web Services for Remote Portlets Specification28

•

portletState: An opaque field the Portlet uses when it depends on the Consumer tostore its persistent state [A205]. If the portletState field has a value, the Consumer
MUST return this value on subsequent calls using the same portletHandle. Note thatsuch uses can span multiple starting and stopping cycles of the Consumer andtherefore this state MUST be persisted by the Consumer until successfully invoking
destroyPortlets() with the related portletHandle.

•

extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

5

6.1.4 Standard UserScopes
1015This specification defines initial values for UserScopes. UserScope is an open set of values
where the Producer SHOULD restrict the values supplied to those specified in this specificationor custom values the Consumer has indicated it supports. If another value is specified and theConsumer does not understand it, the Consumer should ignore the cache control and treat thecontent as non-cacheable. The following values are defined by this specification:•”wsrp:perUser”: The markup is specific to the userContext for which it was generated.
Changes to the data of the UserContext MUST invalidate the cached markup.

•”wsrp:forAll”: The markup is not specific to the UserContext and therefore may besupplied to all users of the Consumer.

6.1.5 CacheControl Type
20

The CacheControl structure contains a set of fields needed for the Portlet to manage cachedmarkup fragments. Note that any key used by the caching system to locate this markup MUST
include the MarkupParams structure that was current when the content was originally cached.
CacheControl[R] int[R] string[O] string[O] Extension

25

expiresuserScopevalidateTag
extensions[]

Members:•

expires: Number of seconds the markup fragment referenced by this cache control
entry remains valid. A value of –1 indicates that the markup fragment will never expire.

•

userScope: A string indicating when the markup may be used by various users. If theConsumer does not know how to process the specified userScope, it MUST NOT

30

cache the markup.
•

validateTag: A string the Consumer MAY use to attempt to revalidate markup oncethe expires duration elapses. This potentially eliminates the need for the Portlet toregenerate the markup and thereby can significantly improve the performance for the
End-User.

•extensions: The extensions field MAY be used to extend this structure. Extension

35

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification29

6.1.6 Templates TypeThe Templates structure contains a set of fields that enable Producer URL writing. The
template style format of these fields is defined in section 10.2.2.
Templates[O] string[O] string[O] string[O] string[O] string[O] string[O] string[O] string[O] Extension

5

10

defaultTemplate
blockingActionTemplate
renderTemplate
resourceTemplate
secureDefaultTemplate
secureBlockingActionTemplate
secureRenderTemplate
secureResourceTemplate
extensions[]

Members:
15•

defaultTemplate: This template provides the default value for all of the othertemplate fields that do not begin with the string “secure”.

•

blockingActionTemplate: This template provides the template for URLs that will bedirected to the Consumer and processed as a performBlockingInteraction() on the
Portlet.

20•

renderTemplate: This template provides the template for URLs that will be directed to

the Consumer and processed as a getMarkup() on the Portlet.

••
25

resourceTemplate: This template provides the template for URLs that will be directedto the Consumer and processed as an HTTP GET on the named resource.
secureDefaultTemplate: This template provides the default value for all the securetemplate fields.
•

secureBlockingActionTemplate: This template provides the template for secure

URLs that will be directed to the Consumer and processed as aperformBlockingInteraction() on the Portlet using a secure protocol.

•

secureRenderTemplate: This template provides the template for secure URLs that will
be directed to the Consumer and processed as a getMarkup() on the Portlet using asecure protocol.

•

secureResourceTemplate: This template provides the template for secure URLs that30

will be directed to the Consumer and processed as an HTTP GET over SSL/TLS on thenamed resource.

35•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from a namespaces other than WSRP.

6.1.7 ClientData TypeThe MarkupParams structure carries information concerning the user agent using this type.
ClientData[O] string[O] Extension

40

userAgentextensions[]

Members:

45•

userAgent: String identifying the user-agent of the End-User.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification30

6.1.8 NamedString TypeThe NamedString type provides a standardized way of carrying a simple name/value pair.
NamedString[R] string[R] string

5

name
value

Members:•

name: The name to be associated with this value.

•

value: The associated value.

6.1.9 MarkupParams Type
10The MarkupParams structure contains a set of fields needed for the Portlet to generate markup
that will enable the End-User to visualize the state of the Portlet. These are also supplied to theinteraction processing operations as they may impact that processing (e.g. validNewModes)
and those operations are allowed to return markup and thereby avoid an additional invocation.
MarkupParams[R] boolean[R] string[R] string[R] string[R] string[O] ClientData[O] string[O] string[O] string[O] string[O] string[O] Extension

15

20

25

secureClientCommuncation
locales[]mimeTypes[]mode
windowState
clientDatanavigationalState
markupCharacterSets[]
validateTagvalidNewModes[]validNewWindowStates[]
extensions[]

Members:

30

35

40

9

•

clientData: A structure (defined in section 6.1.7) that provides information about theclient device which will render the markup.

•

secureClientCommunication: A flag indicating whether or not the delivery channel
between a client and Consumer is secure [R401]. The Consumer MUST set the
secureClientCommunication flag as the Portlet MAY render different content when it
knows the delivery channel is secure.

•

locales: An array of locales where the order in the array is the Consumer’s order ofpreference for the Portlet to generate the markup (e.g. “en-US”). Note that current
practice on the Internet uses the format [2 char language code]9 “-” [2 char countrycode]10 as per the provided example. The Consumer can supply this information basedon the setting the End-User has requested, but is encouraged to also take into accountthe locales the PortletDescription declared were supported for the mime types being
requested.

http://lcweb.loc.gov/standards/iso639-2/langcodes.html
http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/en_listp1.html

10

Web Services for Remote Portlets Specification

31

11

•

(e.g. “text/html”, “application/xhtml+xml”, etc.)
where the order in the array is the order in which the Consumer would prefer the Portlet
generate the markup (i.e. first is most preferred, second is next preferred, etc.). In
addition to these fully specified Mime types, use of “*” (indicates all Mime types are
acceptable) and type/* (where type includes things such as “text”) from the HTTP
definition12 MAY be specified. Portlets SHOULD generate markup in one of thespecified Mime types. The Producer/Portlet does not have to process any optionalparameters that can be included on mime type declarations.

•mode: The mode for which the Portlet should render its output. A set of modes is

5

10

mimeTypes: An array of Mime types

defined in this specification (see section 6.8). In addition, the Portlet’s metadata
indicates which of these modes the Portlet supports as well as any Producer-definedmodes. The Consumer MUST specify either one of the modes from the Portlet’s
metadata or “wsrp:view” (all Portlets are required to support this mode).

•

windowState: The state of this Portlet’s virtual window relative to other Portlets on theaggregated page. Constants and definitions for the specification-defined states arefound in section 6.9. The Consumer MUST specify either one of the windowStates fromthe Portlet’s metadata or “wsrp:normal” (all Portlets are required to support thiswindowState).

•navigationalState: This field contains the opaque navigational state for this portlet.
To exist, navigational state must be set explicitly on each URL activation or by setting
its value upon return from performBlockingInteraction().

•markupCharacterSets: An array of characterSets13 (e.g. “UTF-8”, “ISO-10646-

15

20

Unicode-Latin1”, etc.) the Consumer is willing to have the Portlet use for encoding themarkup (i.e. the character set for the aggregated page). The order of this arrayindicates the preferred ordering of the Consumer with the first element in the array
being the most preferred. When the SOAP binding is in use, the Producer MUST either
use one of the markupCharacterSets, UTF-8 or UTF-16 for the response message as
the nature of XML requires the character set used for the markup to be the same as the
response message.

25

30

•

validateTag: This field MAY contain a validateTag previously supplied to theConsumer in a MarkupContext structure. When this field has a value, the Consumer isindicating it has markup cached for the Portlet, but the CacheControl structure
governing the use of that cached markup no longer indicates it is valid. The Consumer
is supplying the validateTag as a means for the Portlet to avoid generating new
markup if the cached markup can be validated. The Portlet sets the useCachedMarkup
field in the returned MarkupContext to “true” to indicate the markup referenced by thevalidateTag is still valid.

•

validNewModes: Current set of modes the Producer MAY request changing to. Thesecan be used to specify a mode change either via an UpdateResponse or within an URL

3540

written into the returned markup. It should be noted that this is no guarantee that arequested transition will be honored, as factors not easily represented may cause theConsumer to reject a requested transition. The primary reason for supplying thisinformation is to assist the Portlet in preparing a user interface that does not containlinks the Consumer will not honor. If no values are supplied, the Portlet can assume
that all transitions are valid. Consumers can indicate they prohibit all transitions bysupplying just the current mode in this array.

4511

http://www.isi.edu/in-notes/iana/assignments/media-types/media-types
http://www.ietf.org/rfc/rfc2616.txt
13
http://www.iana.org/assignments/character-sets
12

Web Services for Remote Portlets Specification32

•validNewWindowStates: An array of windowStates which the Consumer is indicating
as available to be requested as a newWindowState in UpdateResponse. It should be
noted that this is no guarantee that a requested transition will be honored, as factors
not easily represented may cause the Consumer to reject a requested transition. The
primary reason for supplying this information is to assist the Portlet in preparing a userinterface that does not contain links the Consumer will not honor. If no values aresupplied, the Portlet can assume that all transitions are valid. Consumers can indicate
they prohibit all transitions by supplying just the current windowState in this array.

•extensions: The extensions field MAY be used to extend this structure. Extension

5

10

elements MUST be from namespaces other than WSRP.

Custom modes, windowStates, userScopes and userAuthentication values MUST be URI's
in order to reduce name clashes with any values that may be defined by future versions of thisspecification.

6.1.10 MarkupContext Type
15

The MarkupContext structure contains fields relative to returning markup from various
invocations.
MarkupContext[O] boolean[O] string[O] string[O] base64Binary[O] string[O] boolean[O] CacheControl[O] string[O] Extension

20

25

useCachedMarkup
mimeType
markupString
markupBinary
localerequiresUrlRewriting
cacheControl
preferredTitle
extensions[]

Members:•

useCachedMarkup: A boolean used to indicate whether the markup the Consumer
indicated it has cached is still valid. The default value of this field is “false” (i.e. newmarkup is being returned for the Consumer’s use). If the value for useCachedMarkup is“true” the markupString and markupBinary fields MUST NOT be returned. If the field’svalue is “true”, any supplied cacheControl field MUST be processed as a replacement
for the cacheControl originally supplied with the cached markup.

•

mimeType: The mime type of the returned markup. The mimeType field MUST be
specified whenever markup is returned, and if the markupBinary field is used to returnthe markup, the mime type MUST include the character set for textual mime types
using the syntax specified in RFC152214 (e.g. “text/html; charset=UTF-8”). In thisparticular case this character set MAY be different than the response message.

•

markupString: The markup to be used for visualizing the current state of the Portlet.
This is a string in order to support non-XML markup (e.g. HTML). If this is encoded in a
SOAP message (i.e. XML), various characters will likely need to be escaped using
XML entities (e.g. “<” becomes “&lt;“), either by the Portlet or the Producer’s runtime.
The character set of the markup a Portlet returns MUST either match that requested in
MarkupParams, be UTF-8 or UTF-16. When a SOAP binding is used, the XML
specification requires the character set of the markup match the character set of the
response message’s document. This field is only missing when the useCachedMarkup
flag is “true”. This field is mutually exclusive with returning the markup in themarkupBinary field.

30

35

40

45

14

http://www.ietf.org/rfc/rfc1522.txt

Web Services for Remote Portlets Specification33

•

markupBinary: The markup to be used for visualizing the current state of the Portlet
returned in binary. This is useful if the text is not easily mapped to the string type or an
attachment scheme is in use that moves binary types into separate message parts(e.g. DIME). This field is mutually exclusive with returning the markup in themarkupString field.

•

locale: The locale of the returned markup. The locale MUST be specified whenevermarkup is returned and is NOT REQUIRED to be from the set of requested locales.

•

requiresUrlRewriting: A flag by which the Portlet/Producer indicates whether or not
Consumer-side URL rewriting (see section 10.2.1) is required. The Consumer MUST
parse the markup for URL rewriting if the value of requiresUrlRewriting is “true”.
The default value for this flag is “false”.

•

cacheControl: Defines the caching policies for the returned markup fragment. If thecacheControl field is not supplied, the Consumer MUST treat the returned markup as

510

not cacheable.
15•

preferredTitle: The title the Portlet would prefer to be used in any decoration of themarkup. The locale and markup type, for textual markup types only, of the preferred
title has to be identical to that of the markup.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

20

6.1.11 MarkupResponse TypeThe MarkupResponse structure contains fields for returning various items in response to a
getMarkup() invocation.
MarkupResponse[R] MarkupContext markupContext[O] SessionContext sessionContext[O] Extension
extensions[]

25

Members:•

markupContext: A structure carrying the returned markup and fields related to themarkup.

30•

sessionContext: This structure contains session-oriented fields that may be returned
from various operations, including a new sessionID and the duration before it
expires.

•

extensions: The extensions field MAY be used to extend this structure withelements from namespaces other than WSRP.

35

6.1.12 UpdateResponse TypeThe UpdateResponse structure contains the items normally returned by
performBlockingInteraction().

40

45

UpdateResponse[O] SessionContext[O] PortletContext[O] MarkupContext[R] string[O] string[O] string

sessionContext
portletContext
markupContext
navigationalState
newWindowState
newModeMembers:

Web Services for Remote Portlets Specification34

•sessionContext: This structure contains session-oriented fields that may be returned
from various operations, including a new sessionID and the duration before it
expires.

•

portletContext: This structure is where a Portlet using Consumer-side persistentstorage may return a change in its persistent state, provided the portletState flag inInteractionParams had been set to “readWrite” or “cloneBeforeWrite”. When the
portletState flag had been set to “cloneBeforeWrite”, this may also include a new
portletHandle. The sequence by which a Portlet can otherwise request changing thisstate is described in section 6.3.2.

10•markupContext: Markup may be returned at the end of interaction processing as an
optimization that avoids an additional remote invocation. To ensure End-Users receive
expected behavior from bookmarked pages, it is important that Portlets taking
advantage of this optimization use the navigational state that the Consumer would
have had for invoking getMarkup().

15•

navigationalState: Opaque representation of navigational state which the Portlet isreturning to the Consumer to indicate the navigational state to be supplied togetMarkup() including for page refreshes and page bookmarks. This state is for the
purpose of generating markup. The Consumer SHOULD supply this value as thenavigationalState on the subsequent invocations for this use of the Portlet for atleast the duration of the End-User’s interactions with this aggregated page in order tomaintain End-User state. The Consumer is not required to persist thenavigationalState for longer than this set of interactions, but can provide such apersistence if desired.

•

newWindowState: A request from the Portlet to change the window state. The
Consumer MAY choose to respect this request to change the window state, but since
the Portlet cannot depend on that choice it MUST NOT encode this new window state
into any of its stateful settings. Rather, the Portlet MUST compute any such impact onstateful settings after the Consumer has actually changed the window state.

•

newMode: A request from the Portlet to change the mode. The Consumer MAY choose
to respect this request to change the mode, but since the Portlet cannot depend on thatchoice it MUST NOT encode this new mode into any of its stateful settings. Rather, thePortlet MUST compute any such impact on stateful settings after the Consumer has
actually changed the mode.

5

20

25

30

6.1.13 BlockingInteractionResponse Type
35

The BlockingInteractionResponse structure contains the various items
performBlockingInteraction() can return.
BlockingInteractionResponse[O] UpdateResponse updateResponse[O] string
redirectURL[O] Extension
extensions[]

40

Members:•

updateResponse: This field captures the items returned when the Portlet is notdirecting the user to a different URL. It is mutually exclusive with the redirectURL field.

•

redirectURL: As a result of processing this interaction, the Portlet may indicate to the45Consumer that it would like the End-User to view a different URL. It is mutually
exclusive with the updateResponse field.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification

35

6.1.14 StateChange Type
This type is a restriction on the string type that is constrained to the values “readWrite”,“cloneBeforeWrite” or “readOnly”, the meanings of which are explained in section 6.3.2.

6.1.15 UploadContext Type
5The UploadContext structure contains fields specific to uploading data to the Portlet.
UploadContext[R] string[R] base64Binary[O] NamedString[O] Extension

10

mimeType
uploadData
mimeAttributes[]
extensions[]

Members:

15•

uploadData: A binary data blob that is being uploaded.

•

mimeType: Mime type of what is in the uploadData field. The syntax for this value isdefined in RFC152215 (e.g. “text/html; charset=UTF-8”).

•

mimeAttributes: Mime attributes that are not represented elsewhere.

•

extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

6.1.16 InteractionParams Type20

The InteractionParams structure contains fields specific to invoking theperformBlockingInteraction() operation.
InteractionParams[R] StateChange[O] string[O] NamedString[O] UploadContext[O] Extension

25

portletState
interactionState
formParameters[]
uploadContexts[]
extensions[]

Members:•30

portletState: A flag by which a Consumer indicates whether or not the processingof the interaction is allowed to return a modified portletState. This flag is needed; as

only the Consumer knows whether or not such a state change would be acceptable. In
many cases where the Consumer does not authorize the End-User to modify thepersistent state of the Portlet in use, it may permit the Producer to clone the Portlet (i.e.
set portletState to “cloneBeforeWrite”) and return a clone of the Portlet in addition
to any other return parameters. The full use of this flag is described in section 6.3.2.

35

40

•

interactionState: Opaque representation of transient information for use inprocessing this invocation of performBlockingInteraction(). The value for this field is
supplied through the portlet URL parameter wsrp-interactionState (see section
10.2.1.3).

•

formParameters: Name/value pairs reflected, for example, in the case of HTML either

from the query string of forms submitted with method=get or in a request with mime
type = “application/x-www-form-urlencoded” for method=post. For the case of query
string parameters, Consumers should take care with regard to how user-agents encode
this data. In particular, common user-agents (i.e. web browsers) encode posted data in

15

http://www.ietf.org/rfc/rfc1522.txt

Web Services for Remote Portlets Specification

36

•

5

•

the character set of the response that generated the page the form is on. As the
Producer is ignorant of this encoding and the Consumer is required to consistently
encode parameters passed to the Producer in the SOAP message, Consumers MUST
ensure that form data is properly decoded before it is passed to the Producer.
uploadContexts: An optional field where mime types not parsed into formParameters
are placed for transfer to the Producer.
extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.17 User Profile Types
10

15

The UserProfile structure is used to carry information about the End-User. The Portlet uses
the userProfileItems in its metadata to describe the fields it uses to generate markup fromthis set and any others the Consumer indicated were available when it registered. See Section
11 for a complete description of this portion of the protocol. We expect that most extensions of
the types referenced by UserProfile will be of the type NamedString and encourage its reusein this manner.
UserProfile[O] PersonName[O] dateTime[O] string[O] EmployerInfo[O] Contact[O] Contact[O] Extension

20

name
bdate
genderemployerInfo
homeInfobusinessInfo
extensions[]

Members:25•

name: A structure containing the various fields for the End-User’s name.

•bdate: The End-User’s birthdate. This uses the schema-defined datatype for

DateTime rather than Date as not all web stacks serialize / deserialize Date properly.

••30

gender: The End-User’s gender (“M” = male, “F” = female).
employerInfo: A structure containing various fields for the End-User employer’s

information.
•

homeInfo: The End-User’s home location information.

•businessInfo: The End-User’s work location information.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

35

6.1.17.1

PersonName TypeThe PersonName structure carries the detailed fields for the parts of an End-User’s name.
PersonName[O] string[O] string[O] string[O] string[O] string[O] string[O] Extension

40

45

prefixgiven
familymiddlesuffixnickname
extensions[]

Members:•

prefix: Examples include Mr, Mrs, Ms, Dr, etc.

Web Services for Remote Portlets Specification

37

5

•

given: The End-User’s first or given name.

•family: The End-User’s last or family name.

•middle: The End-User’s middle name(s) or initial(s).

•suffix: Examples include Sr, Jr, III, etc.

•

nickname: The End-User’s preferred nick name.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.17.2

EmployerInfo TypeThe EmployerInfo structure contains the detailed fields concerning the End-User’s employer.
1015

Employerinfo[O] string[O] string[O] string[O] Extension

employer
department
jobtitle
extensions[]

Members:

20•

employer: The name of the employer.

•

department: The name of the department the End-User works within.

•

jobTitle: The title of the End-User’s job.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.17.3

TelephoneNum TypeThe TelephoneNum structure is used to describe the subfields of a phone number.
TelephoneNum[O] string[O] string[O] string[O] string[O] string[O] Extension

25

30

35

intcodeloccodenumberext
comment
extensions[]

Members:•

intcode: The international telephone code.

•

loccode: Local telephone area code.

•

number: The telephone number.

•

ext: Any telephone number extension.

•comment: Comment about this phone number.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification

38

6.1.17.4

Telecom TypeThe Telecom structure is used to describe the various phone contact information.
Telecom[O] TelephoneNum telephone[O] TelephoneNum fax[O] TelephoneNum mobile[O] TelephoneNum pager[O] Extension
extensions[]

5

Members:
10•

telephone: Standard phone number.

•

fax: Phone number for faxes.

•

mobile: Phone number for mobile contact.

•

pager: Phone number for activating a pager.

•

extensions: The extensions field MAY be used to extend this structure. Extension

15

elements MUST be from namespaces other than WSRP.

6.1.17.5

Online TypeThe Online structure is used to describe the various phone contact information.
Online[O] string[O] string[O] Extension

20

email
uri
extensions[]

Members:

25•

email: Email address.

•

uri: Relevant web page.

•extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.17.6

Postal TypeThe Postal structure carries the detailed fields describing a particular address.
Postal[O] string[O] string[O] string[O] string[O] string[O] string[O] string[O] Extension

30

35

name
streetcity
stateprov
postalcode
countryorganization
extensions[]

Members:40•

name: The name to which items should be addressed.

•

street: The street portion of the address.

•

city: The city portion of the address.

•

stateprov: The state or province portion of the address.

•

postalcode: The postal code portion of the address.

Web Services for Remote Portlets Specification39

•

country: The country portion of the address.

•

organization: Any organization needing to be specified in the address.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

5

6.1.17.7

Contact TypeThe Contact structure is used to describe a location for the End-User.
Contact[O] Postal[O] Telecom[O] Online[O] Extension

10

postaltelecom
onlineextensions[]

Members:

15•

postal: Postal oriented contact information.

•

telecom: Telephone oriented contact information..

•

online: Web oriented contact information.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

6.1.18 UserContext Type
20

The UserContext structure supplies End-User specific data to operations. Note that this does
not carry user credentials (e.g. userID / password) as quite flexible mechanisms forcommunicating this information are being defined elsewhere (e.g. WS-Security (see section
3.1.2) defines how to carry User Information in a SOAP header).
UserContext[R] Key[O] string[O] UserProfile[O] Extension

25

userContextKey
userCategories[]
profileextensions[]

Members:•30

userContextKey: This key is a token that the Consumer supplies to uniquely identify
the UserContext. The userContextKey MUST remain invariant for the duration of a

Consumer’s registration. The Producer can use this key as a reference to the user.

•

user category in which the Consumer places the End-User relative to the current
operation. The Consumer MUST NOT assert a user category for which no
ItemDescription was part of the Producer’s ServiceDescription. See thediscussion of user categories in section 6.10.

35

40

userCategories: An array of strings, each of which specifies an Producer-defined•

profile: End-User profile data structure as defined in section 6.1.17. Note that while
the UserContext structure is passed to many operations, only the interaction oriented
operations need this optional field to be supplied.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification406.2 getMarkup() Operation
The Consumer requests the markup for rendering the current state of a Portlet by invoking:5

10

MarkupResponse = getMarkup(RegistrationContext, PortletContext, RuntimeContext,
UserContext, MarkupParams);
Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle, Interface.InvalidCookie, Interface.InvalidSession,
Interface.UnsupportedMode, Interface.UnsupportedWindowState
Interface.UnsupportedLocale, Interface.UnsupportedMimeType

6.2.1 Caching of markup fragments

15

For performance reasons the Consumer might prefer to cache markup across a series ofrequests. The Producer passes information about the cacheability of the markup fragment in
the cacheControl structure returned in a MarkupContext structure. The Consumer can inferfrom this information when it may cache markup and when the cached markup needs to beinvalidated and updated by a new call to getMarkup().

6.2.1.1 Cacheability

20

Whenever the cacheControl field of a MarkupResponse structure is filled in the Consumer
MAY cache the markup fragment. The Consumer MUST follow the defined invalidation
policies from section 6.2.1.2 in order to keep the cache up-to-date. If the cacheControl fieldis empty, the Consumer MUST NOT cache the markup fragment.

6.2.1.2 Cache Invalidation

25

The expires field of the cacheControl structure provides a time duration during which it isvalid to supply the markup from a cache. Once this time has elapsed, counting from the point
in time when the MarkupContext structure was returned, the Consumer can use thevalidateTag field of the MarkupParams structure to inquire whether the markup is still valid,
as this potentially avoids having the Portlet regenerate the same markup. Portlets indicating
the cached markup can be used SHOULD also supply a new CacheControl structure with a
new expiry for the markup.

30
Consumers should be aware that invoking performBlockingInteraction() may cause cachedmarkup to become invalid. This version of the specification does not address how a Portlet
can indicate that cached markup is invalid, but it is anticipated that future versions willaddress this issue.
35

6.3 Interaction Operations

40

End-User interactions with the generated markup may result in invocations for the Portlet torespond to the interactions [A400]. In the case where the invocations may change thenavigationalState or some data the Portlet is storing in a shared data area (including a
database), an operation is needed to carry the semantics of this type of update. The Consumer
MUST always propagate these End-User interactions to the Producer.

Web Services for Remote Portlets Specification

41

6.3.1 performBlockingInteraction() Operation

5

10

15

20

25

This operation requires that both the Consumer beginning the generation of the aggregatedpage (because the invocation can return a redirectURL), invoking other operations on Portlets
and the gathering of markup from other Portlets on the page (often because shared state,including state shared via a database, impacts the markup of other Portlets) are blocked until
performBlockingInteraction() either returns or communication errors occur. The Portlet will
receive only one invocation of performBlockingInteraction() per client interaction, excepting
for retries.
BlockingInteractionResponse = performBlockingInteraction(RegistrationContext,
PortletContext, RuntimeContext, UserContext,
MarkupParams, InteractionParams);
Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle, Interface.InvalidCookie, Interface.InvalidSession,
Interface.UnsupportedMode, Interface.UnsupportedWindowState
Interface.UnsupportedLocale, Interface.UnsupportedMimeType
Interface.PortletStateChangeRequired

The Consumer has to wait for the response from performBlockingInteraction() before
invoking getMarkup() on the Portlets it is aggregating. This permits any Producer-mediatedsharing to proceed safely (provided it happens in a synchronous manner). Since this operation
potentially returns state to the Consumer for storage, this operation also allows Consumers
who wish to store this by propagating it to their client to do so before opening the stream for theaggregated page. Consumers doing this also enable End-User bookmarking of the aggregatedpage for later use. In order to support such bookmarking and reduce issues related topotentially reinvoking a transaction for the End-User, Consumers are encouraged to redirect
the client in a manner that keeps a bookmarked page from reissuing a request to invoke
performBlockingInteraction(). Producer still need to be prepared for such repeatedinvocations as the End-User may activate the link that caused the invocation more than once.

3035Note, if the Producer chooses to use the optimized form of this operation and return markup
directly, care must be taken to ensure the markup is generated with the navigationalState
that will be returned from the operation and not the navigationalState that was passed to it.
This ensures consistency when the optimization is not used and the Consumer invokes
getMarkup() after performBlockingInteraction() returns.

6.3.2 Updating Persistent Portlet StateIn designing how a Portlet and Consumer interact in order to update the persistent state of thePortlet, the following items were considered:40

1. Only the Portlet knows when such a state change is desired. While it is expected thatchanges to persistent state will be relatively rare, they could occur on any interaction
the Portlet has with an End-User.

45

2. Only the Consumer knows whether or not a persistent state change would be safe.
Reasons for this include whether the persistent state is shared among a group ofusers, the authorization level of the End-User to impact any shared persistent state andConsumer policies regarding whether the persistent state is modifiable.

50

This combination requires that all persistent Portlet state changes happen in a manner that has
Consumer approval for the change to occur, while the Portlet decides both when the change isrequired and its exact character. The Consumer indicates whether or not it is safe for thePortlet to modify its persistent state by setting the portletState field in theInteractionParams structure. If the Consumer has set the portletState flag to “readWrite”,

Web Services for Remote Portlets Specification

42

the Portlet MAY modify its persistent state regardless of whether it is persisted on the Producer
or Consumer.

5

10

If the Consumer has set the portletState field to “cloneBeforeWrite”, persistent statechanges are allowed only if the Producer first clones the Portlet. If the Producer does not clone
the Portlet, processing attempts to modify persistent state MUST proceed as if the Consumer
had specified “readOnly” for portletState. If the Producer clones the Portlet, processing
attempts to modify persistent state on the new Portlet SHOULD proceed as if the Consumer
had specified “readWrite” for portletState. The Producer returns the impact of any cloning
to the Consumer, regardless of whether the portletState is persisted on the Producer orConsumer. If the Producer returns a new portletHandle without returning a new sessionID,
the Consumer MUST associate the current sessionID with the new portletHandle rather
than the previous portletHandle. The metadata associated with the original Portlet applies toany cloned Portlet as well.

15

20

If the Consumer has set the portletState flag to ”readOnly”, the Portlet MUST NOT modify
its persistent state regardless of whether it is persisted on the Producer or Consumer and
MUST throw a fault message if processing the interaction requires changing its persistent state.
Commonly Consumer’s will only set the portletState flag to “readOnly” for End-Users thatare not authorized to clone or customize the Portlet (e.g. an End-User using a guest account).

25

If the Producer implements access control that prevents Portlets from updating persistent state
and a Portlet is unable to process the interaction without such an update, then the fault“Interface.PortletStateChangeRequired” MAY be thrown indicating the interaction
processing failed.
This set of possibilities is depicted in the following figure:6.4 initCookie() Operation
30

In general, the Producer completely manages its own environment, including items such as theinitialization of cookies when using the HTTP transport. There are cases, however, when
Web Services for Remote Portlets Specification

43

assistance from the Consumer in initializing these cookies is useful. Cookies needed to
manage distribution of requests within a load balanced environment are an example of such.
This operation is how the Consumer provides such assistance:
ReturnAny = initCookie(RegistrationContext);
Faults: Security.AccessDenied, Security.InvalidRegistration,
Interface.OperationFailed

5

10

If the Producer’s metadata has set the requiresInitCookie field to any value other than“none”, then the Consumer MUST invoke initCookie() and supply any returned cookies
according to the semantics of the value of requiresInitCookie as defined in section 5.1.18. If
at any time the Producer throws a fault message (“Interface.InvalidCookie”) indicating the
supplied cookies have been invalidated at the Producer, then the Consumer MUST again
invoke initCookie() and SHOULD reprocess the invocation that caused the fault message tobe thrown and include any data that may have been stored in a session related to a cookie.

6.5 releaseSessions() Operation
15

The Consumer MAY inform the Producer that it will no longer be using a set of sessions by
invoking releaseSessions() (e.g. the Consumer is releasing resources related to thesessionIDs):
ReturnAny = releaseSessions(RegistrationContext, sessionIDs);
Faults: Security.AccessDenied, Security.InvalidRegistration,
Interface.MissingParameters, Interface.OperationFailed

20

After invoking releaseSessions() the Consumer MUST NOT include any of the supplied
sessionIDs on subsequent invocations.

6.6 Consumer Transitions across Bindings
25

30

Consumers need to be careful about the support supplied by the web stack with regards tomultiple bindings that will be offered by many Producers. If a Producer indicates that it uses
cookies, the Consumer MUST ensure that any cookies the Producer sets are available on all
invocations within the Markup interface. Another implication of the Producer indicating it uses
cookies is that the Consumer should be aware of the issues involved in protocol transitions(e.g. from HTTP to HTTPS). Current technologies do not always manage cookies in a mannerthat allows cookies to be shared across such a transition. In addition, moving cookies from an
HTTPS to an HTTP connection opens security issues that MUST be handled in the mannerprescribed in RFC210916. Consumers MUST respect the security setting on each cookie.

6.7 Stateful Portlet Scenarios
35

There are several common scenarios for Portlets with varying needs regarding statefulness[A202][A203]. This section explains how they map into the operational signatures above.

6.7.1 No State

40

This type of Portlet maintains no state, but encodes everything required to generate the markup
on the URL causing the invocation of getMarkup() [A201]. Often these Portlets involve only asingle page, but could provide links on that page that cause the generation of a completely
different markup due to the parameters passed when the link is activated.

16

http://www.ietf.org/rfc/rfc2109.txt

Web Services for Remote Portlets Specification

44

Note: Invocations of performBlockingInteraction() can happen in this scenario if the Portlet
impacts some backend system as a result of the invocation as this impact could change themarkup some other Portlet will generate.
5

The following table outlines the values for certain key parameters that support this scenario.
MethodParameter/Field

Value

Comments

performBlockingInteraction

SessionContext /sessionID

Producer provided
sessionContext /sessionIDNo value as this Portlet uses
no Producer-side state.

InteractionParameters / interactionState

Consumer extracts
value from link.

Interaction state encoded on
the URLs in the markup only.

MarkupParams /navigationalState

Consumer extracts
value from link.

Navigational state encodedon the URLs in the markup
only.

InteractionResponse /navigationalState

This type of Portlet
does not returnnavigationalState.

SessionContext /sessionID

Producer provided
sessionContext /sessionIDNo value as this Portlet uses
no Producer-side state.

MarkupParams /navigationalState

Consumer extracts
value from link.

Navigational state from the
URL.

getMarkup

6.7.2 Navigational State Only

10

15

20

This type of Portlet does not maintain state at the Producer, but does push navigational stateout to the Consumer. Both to support these Portlets and to assist Consumers in properly
supporting End-User page refreshes and bookmarks, Portlets are allowed to return theirnavigational state (i.e. the navigationalState field) back to the Consumer. It is then the
responsibility of the Consumer to retransmit the navigationalState to the Producer with eachrequest [A206].
A stateless Consumer can store the navigationalState for all of its aggregated Portlets byreturning them to the client, for example by encoding them in the URL. Since this
implementation option requires the URL to be generated before the output stream is opened,
the navigationalState of all Portlets must be known before the Consumer begins generating
the output stream. In order to allow the Consumer to open the output stream before it hascollected markup from all Portlets aggregated on the page, a getMarkup() invocation is notallowed to modify the navigationalState. Only invocations of performBlockingInteraction()
are allowed to modify the navigationalState of a Portlet.

Web Services for Remote Portlets Specification

45

The following table outlines the values for certain key parameters that support this scenario.
MethodParameter/Field

Value

Comments

performBlockingInteraction

SessionContext /sessionID

Producer provided
sessionContext / sessionID

No value as thisPortlet uses no
Producer-side state.

InteractionParams /interactionState

Consumer extracts value
from link.

Interaction state
encoded on the
URLs in the markup
only.

MarkupParams /navigationalState

Consumer extracts value
from link or previous value.

InteractionResponse /navigationalState

Portlet may compute achanged navigationalState.

SessionContext /sessionID

Producer provided
sessionContext / sessionID

MarkupParams /navigationalState

From link or fromperformBlockingInteraction.

getMarkup

No value as thisPortlet uses no
Producer-side state.

6.7.3 Local state
5

10Portlets storing state locally on the Producer establish a session and return an opaquereference (i.e. a sessionID) which the Consumer then returns on all subsequent invocations of
this Portlet instance on the aggregated page for this End-User in order to reconnect the Portlet
to the state stored in the session. These Portlets can also push navigational state to theConsumer such that an End-User may bookmark some portion of the state for use in later
conversations. The means by which the Consumer enables this functionality for the End-Useris a Consumer implementation choice [A304].

Web Services for Remote Portlets Specification

46

The following table outlines the values for certain key parameters that support this scenario.
MethodperformBlockingInteraction

getMarkup

Parameter/Field

Value

Comments

SessionContext /sessionID

Producer provided
sessionContext / sessionID

With Producer sidestate, the session
handle offers ability tostore information
without impacts
message size toConsumer.

InteractionParams /interactionState

Consumer extracts value
from link.

Interaction state
encoded on the URLs in
the markup only.

MarkupParams /navigationalState

Consumer extracts value
from link or previous value.

InteractionResponse /navigationalState

Portlet may compute achanged navigationalState.

SessionContext /sessionID

Producer provided
sessionContext / sessionID

MarkupParams /navigationalState

From link or fromperformBlockingInteraction.

With Producer sidestate, the session
handle offers ability tostore information
without impacts
message size toConsumer.

6.8 Modes
5

10

A Portlet should render different content and perform different activities depending on its
current state, the operation (with parameters) currently being processed, and the functionality
requested by the End-User. A base set of functions is defined which reflects those common for
portal-portlet interactions. They are referred to as modes and should be thought of as how theConsumer is managing the interaction with the End-User. Portlets may request mode changes
either through parameters on a link that an End-User activates or by returning a newMode in a
BlockingInteractionResponse. Whether or not such a request is honored is up to theConsumer and often will depend on access control settings for the End-User.
During getMarkup()and performBlockingInteraction() invocations the Consumer indicates to
the Portlet its current mode via the MarkupParams data structure.

15

Because modes are an extensible set of values, the following semantics apply relative todetermining what modes are valid for the interactions of a Consumer with a Portlet:
1. Portlets specify what modes are supported through their PortletDescription. The
Producer determines whether or not this information is available to the Consumer prior
to registration.

20

2. During registration the Consumer informs the Producer about modes it uses onaggregated pages.
3. After registration, the PortletDescription can dynamically modify the set of modes
supported to incorporate those specified by the Consumer during registration.

Web Services for Remote Portlets Specification

47

4. The Consumer is required to use one of the modes specified by thePortletDescription (or the required “wsrp:view” mode).

6.8.1 “wsrp:view” Mode
510The expected functionality for a Portlet in wsrp:view mode is to render markup reflecting thecurrent state of the Portlet. The wsrp:view mode of a Portlet will include one or more screensthat the End-User can navigate and interact with or it may consist of static content devoid ofuser interactions.
The behavior and the generated content of a Portlet in the wsrp:view mode may depend on
configuration, personalization and all forms of state.
Conformant Portlets MUST support the wsrp:view mode.

6.8.2 “wsrp:edit” Mode
15

20

Within the wsrp:edit mode, a Portlet should provide content and logic that let a user
customize the behavior of the Portlet. The wsrp:edit mode can include one or more screens
which users can navigate to enter their customization data.
Typically, Portlets in wsrp:edit mode will set or update Portlet state by making these changes
persistent for the Portlet. How such changes impact Consumer management of Portlet usage
by End-Users is discussed in section 6.3.2.

6.8.3 “wsrp:help” Mode
When in wsrp:help mode, a Portlet may provide help screens that explains the Portlet and its
expected usage. Some Portlets will provide context-sensitive help based on the markup the
End-User was viewing when entering this mode.
25

6.8.4 “wsrp:preview” ModeIn wsrp:preview mode, a Portlet should 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 thecurrent configuration. This could be useful for a Consumer that offers an advanced layout
capability.

30

35

6.8.5 Custom Modes
The extensible RegistrationData structure provides a field for Consumers to declareadditional custom modes. In addition, the extensible PortletDescription structure provides afield for Portlets to declare what modes they understand. The Portlet could receive a mode it
does not currently support as it may have existed in a previous PortletDescription. A Portlet
MUST map any mode it does not understand to the wsrp:view mode. Custom mode values
are required to be URI's in order to reduce name clashes with any values that may be definedby other parties, including future versions of this specification.

6.9 Window States
40

Window state is an indicator of the amount of page space that will be assigned to the content
generated by a Portlet. This hint is provided by the Consumer for the Portlet to use when
deciding how much information to render in the generated markup.

Web Services for Remote Portlets Specification48

Because window states are an extensible set of values, the following semantics apply relative
to determining what window states are valid for the interactions of a Consumer with a Portlet:

5

1. Portlets specify what window states are supported through their PortletDescription.
The Producer determines whether or not this information is available to the Consumer
prior to registration.
2. During registration the Consumer informs the Producer about window states it uses onaggregated pages.
3. After registration, the PortletDescription can dynamically modify the set of window
states supported to incorporate those specified by the Consumer during registration.

10

4. The Consumer is required to use one of the window states specified by thePortletDescription (or the required “wsrp:normal” window state).

6.9.1 “wsrp:normal” Window State15

The wsrp:normal window state indicates the Portlet is likely sharing the aggregated page withother Portlets. The wsrp:normal window state MAY also indicate that the target device has
limited display capabilities. Therefore, a Portlet SHOULD restrict the size of its rendered output
in this window state.
Conformant Portlets MUST support the wsrp:normal window state.

6.9.2 “wsrp:minimized” Window State
20

When the window state is wsrp:minimized, the Portlet SHOULD NOT render visible markup,
but is free to include non-visible data such as JavaScript or hidden forms. The getMarkup()
operation can be invoked for the wsrp:minimized state just as for all other window states

6.9.3 “wsrp:maximized” Window State25

The wsrp:maximized window state is an indication the Portlet is likely the only Portlet being
rendered in the aggregated page, or that the Portlet has more space compared to otherPortlets in the aggregated page. A Portlet SHOULD generate richer content when its window
state is wsrp:maximized.

6.9.4 “wsrp:solo” Window State30

The wsrp:solo window state is an indication the Portlet is the only Portlet being rendered in
the aggregated page. A Portlet SHOULD generate richer content when its window state is
wsrp:solo.

6.9.5 Custom Window States
35

40

The extensible RegistrationData structure provides a field for Consumers to declareadditional custom window states. In addition, the extensible PortletDescription structure
contains a field for Portlets to declare what window states they understand. The Portlet could
receive a window state it does not currently support as it may have existed in a previous
PortletDescription. A Portlet MUST map any window state it does not understand to
wsrp:normal. Custom windowState values are required to be URI's in order to reduce nameclashes with any values that may be defined by other parties, including future versions of thisspecification.

Web Services for Remote Portlets Specification

49

6.10 User Categories

5

A Producer’s ServiceDescription MAY declare support for user categories. A Consumer
MAY map End-Users to the user categories a Producer declares in any manner it chooses,
including ignoring them. Producers that use user categories SHOULD implement appropriate
default behavior in the event a Consumer does not assert any user category for the End-User.
A Portlet optionally declares the user categories for which it personalizes markup in the
PortletDescription structure described in section 5.1.11. The Consumer may assert any of

10these categories on behalf of a user. Since the Producer has no means of authenticating that
the End-User belongs to one of these categories, this assertion should not be used for any
security related purposes. If such an authentication is desired, standard security protocols
should be employed to provide the authentication.

6.10.1 User Category Assertions
15

Since user categories are an optional means for the Producer and Consumer to cooperatively
apply personalization that are relevant to the user, the following examines the various
combinations of Producer and Consumer choices:
1. Neither Producer nor Consumer support user categories. In this case thePortletDescription structures from the Producer will not declare any user categories
and the Consumer will never assert any user categories in the UserContext structure.

20

25

2. Both the Producer and Consumer support user categories. In this case thePortletDescription structures from the Producer will declare user categories. The
Consumer will need to map its information about the user to this set from the Producer
when asserting user categories in the UserContext structure in order to satisfy therequirement that the asserted user categories come only from the Producer publisheduser categories. The Consumer controls the mechanism by which this mapping occurs.
3. Producer supports user categories, but the Consumer does not. In this case thePortletDescription structures from the Producer declare user categories, but theConsumer will never assert any user categories in the UserContext structure. The
Producer will need to default the user category it uses to process invocations.

30

4. The Producer does not support user categories, but the Consumer does. In this case
the PortletDescription structures from the Producer will not declare any user
categories and the Consumer MUST NOT assert any user categories in the
UserContext structure.

7 Registration Interface
35

A Producer that supports in-band registration of Consumers exposes the optional registrationinterface. Regardless of whether or not the registration portType is exposed, Producers canoffer out-of-band processes to register a Consumer. All Producer registration processes MUST
result in a unique, opaque token that may be used to refer to the registration. This specification
calls this token a registrationHandle (defined in section 5.1.21).

40

7.1 Data Structures
The normative definitions for all data structures are contained in the WSDL referenced in
section 14. For the convenience of the reader, this non-normative section uses an IDL likesyntax to describe these structures, where the leading [R] indicates a field is required and [O]indicates it is optional. The operations in this section introduce the following data structures:

Web Services for Remote Portlets Specification50

7.1.1 RegistrationData TypeThe RegistrationData structure provides the means for the Consumer to supply the datarequired for registration with a Producer as well as protocol extensions that it supports[R355][R356].
5

RegistrationData[R] string[R] string[R] boolean[O] string[O] string[O] string[O] string[O] Property[O] Extension

10

15

consumerName
consumerAgentmethodGetSupported
consumerModes[]consumerWindowStates[]
consumerUserScopes[]customUserProfileData[]
registrationProperties[]
extensions[]

Members:•

consumerName: A name (preferably unique) that identifies the Consumer [R355]. An
example of such a name would be the Consumer’s URL.

•

consumerAgent: Name and version of the Consumer’s vendor [R356]. The
consumerAgent value MUST start with “productName.majorVersion.minorVersion”

20

where “productName” identifies the product the Consumer installed for its deployment,
and majorVersion and minorVersion are vendor-defined indications of the version of its
product. This string can then contain any additional characters/words the product orConsumer wish to supply.
•

25

methodGetSupported: A flag that tells the Producer whether the Consumer has

implemented portlet URLs (regardless of whether they are written through Consumer
URL rewriting or Producer URL writing, see section 10.2) in a manner that supports
HTML markup containing forms with method=”get”.

•

consumerModes: An array of modes the Consumer is willing to manage. This

specification defines a set of constants for a base set of modes (see section 12). This
array may reference both those constants and additional custom modes of theConsumer.

30•

consumerWindowStates: An array of window states the Consumer is willing tomanage. This specification defines a set of constants for a base set of window states(see section 12). This array may reference both those constants and additional custom
window states of the Consumer.

•

consumerUserScopes: This field specifies the all the values for UserScope the35

Consumer is willing to process, including those defined by this specification. If theConsumer fails to supplies any values for this field, the Producer is free to specify anyof the values defined by this specification.

40•

customUserProfileData: An array of strings each of which name a UserProfile

extension the Consumer supports.

•

registrationProperties: List of registration properties. The names of theseproperties SHOULD be from the set declared in theregistrationPropertyDescription from the Producer’s ServiceDescription and45

are not part of this specification.
•

extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification

51

7.2 register() Operation

5

10

15

20

Registration describes how a Consumer establishes a relationship with a Producer that will bereferenced via an opaque handle in subsequent invocations the Consumer makes of the
Producer [R350]. Both the Consumer and the Producer are free to end this relationship at any
time [R500]. When the Consumer chooses to end the relationship, it MUST attempt an
invocation of the deregister() operation so that the Producer may release related resources.
When the Producer chooses to invalidate the registration identifier, it MUST inform theConsumer of this through a fault message on the next invocation specifying thisregistrationHandle so that the Consumer may release related resources.
RegistrationContext = register(RegistrationData);
Faults: Interface.MissingParameters, Interface.OperationFailed

The returned RegistrationContext is used in all subsequent invocations to reference thisregistration [R362]. If the Producer’s metadata declares registration is not supported (i.e.
requiresRegistration flag was set to “false”), then it MUST be valid to not supply a
RegistrationContext to operations with this parameter. Whenever the registration attempt
fails a fault message MUST be thrown indicating this to the Consumer [R363].
A Producer supporting registration MUST allow a Consumer to register itself multiple times withpotentially different settings (e.g. billing settings) resulting in multiple registrationHandles[R351].

7.3 modifyRegistration() Operation
This operation provides means for the Consumer to modify a relationship with a Producer[R353].
25

30

RegistrationState = modifyRegistration(RegistrationContext, RegistrationData);
Faults: Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed

The supplied parameters reference a pre-existing registration and the modifications desired. If
the Producer chooses to have the Consumer provide persistent storage, the entire resulting
registration state is carried in the registrationState field of the returned
RegistrationState structure.

7.4 deregister() Operation
The Consumer MUST NOT consider a relationship with a Producer ended until either asuccessful invocation of deregister() or receipt of a Security.InvalidRegistration fault
message from the Producer on an invocation supplying the registrationHandle.
35

40

45

ReturnAny = deregister(RegistrationContext);
Faults: Security.InvalidRegistration, Interface.OperationFailed

After this operation is invoked, all handles created within the context of theRegistrationContext become invalid [R500][R501][R503]. It is a Producer implementation
choice whether this immediately aborts in-progress operations or waits until all transient
resources time out. The Consumer MUST NOT use an invalidated registrationHandle,
where the invalidation occurs either by passing the handle to deregister() or by receiving a
Security.InvalidRegistration fault message from the Producer on an invocation supplying
the handle. The Producer MUST return a Security.InvalidRegistration fault message
whenever a Consumer supplies an invalid registrationHandle. If the deregister() operation
fails, the Producer MUST return a fault message specifying the reason for the failure.

Web Services for Remote Portlets Specification52

8 Portlet Management Interface
5

10

15

Producers MUST expose one or more logically distinct ways of generating markup andhandling interaction with that markup [A205], which this specification refers to as Portlets. The
Producer declares the Portlets it exposes through its description [A104]. This declaration
contains a number of descriptive parameters; in particular it includes a portletHandle that
Consumers use to refer to the so-called “Producer Offered Portlet”. These Portlets are preconfigured and non-modifiable by Consumers.
In addition to the Producer Offered Portlets, a Producer can expose the PortletManagement
portType and thereby allow Consumers to clone and customize the Portlets the Producer
offers. A Consumer MAY request a unique configuration of one of these Portlets, either in an
opaque manner (e.g. the “edit” button common on aggregated pages which invokes a Portletgenerated page for setting the configuration) or by using the property definitions found in the
Portlet’s metadata to configure it in an explicit manner [R600]. Such a configured Portlet iscalled a “Consumer Configured Portlet”.
Any Producer that supports cloning portlets on performBlockingInteraction() invocations
MUST support the releasePortlet() operation.

8.1 Data Structures
20

The normative definitions for all data structures are contained in the WSDL referenced in
section 14. For the convenience of the reader, this non-normative section uses an IDL likesyntax to describe these structures, where the leading [R] indicates a field is required and [O]indicates it is optional. The operations in this section introduce the following data structures:

8.1.1 DestroyFailed Type
25

The DestroyFailed structure contains a portletHandle that was not destroyed and thereason for the failure.
DestroyFailed[R] Handle portletHandle[R] string reason

30

Members:•

portletHandle: The portletHandle that was not destroyed.

•reason: A fault code from section 13 describing the reason the destroy failed.

8.1.2 DestroyPortletsResponse TypeThe DestroyPortletsResponse structure carries an array of failed destroys.
35

DestroyPortletsResponse[O] DestroyFailed
destroyFailed[][O] Extension
extensions[]

Members:•40

destroyFailed: An array of failures returned by destroyPortlets(). This is carried asa return message since not all web stacks properly handle typed information in fault
messages.

•

extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

Web Services for Remote Portlets Specification

53

8.1.3 PortletDescriptionResponse TypeThe PortletDescriptionResponse structure contains the fields that getPortletDescription()can return.
PortletDescriptionResponse[R] PortletDescription
portletDescription[O] ResourceList
resourceList[O] Extension
extensions[]

5

Members:
10•

portletDescription: The metadata for the Portlet.

•

resourceList: This is an array of Resource structures, each of which carries thevalues for a localized resource in various locales.

•

extensions: The extensions field MAY be used to extend this structure. Extension
elements MUST be from namespaces other than WSRP.

8.1.4 PortletPropertyDescriptionResponse Type
15

The PortletPropertyDescriptionResponse structure contains the fields that
getPortletPropertyDescription() can return.
PortletPropertyDescriptionResponse[O] ModelDescription modelDescription[O] ResourceList
resourceList[O] Extension
extensions[]

20

Members:

25•

modelDescription: The description of the Portlet’s properties.

•

resourceList: This is an array of Resource structures, each of which carries thevalues for a localized resource in various locales.

•

extensions: The extensions field MAY be used to extend this structure. Extension

elements MUST be from namespaces other than WSRP.

8.2 getPortletDescription() Operation
This operation allows a Producer to provide information about the Portlets it offers in a contextsensitive manner.
30

35

PortletDescriptionResponse = getPortletDescription(RegistrationContext, PortletContext,
UserContext, desiredLocales);Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle

Producers may choose to restrict access to the information returned in
PortletDescriptionResponse based on the supplied registration and user contexts.

40

Consumers may choose to alter how they interact with a Portlet based on the metadata
contained in the returned PortletDescriptionResponse. For security reasons related to
exposing the existence of something the caller is not allowed to access, it is RECOMMENDED
that a Security.AccessDenied fault be generated both for the case of the supplied
portletHandle not being a valid reference in the scope of the supplied registrationHandle
and for the case of the user not having access to a valid reference (i.e. by definition access isdenied when the Portlet reference is invalid).

45
Web Services for Remote Portlets Specification

54

When generating the PortletDescriptionResponse the Producer SHOULD use thedesiredLocales to control what locales are supplied for localized strings.

8.3 clonePortlet() Operation
5

10

15

This operation allows the Consumer to request the creation of a new Portlet from an existing
Portlet.
PortletContext = clonePortlet(RegistrationContext, PortletContext, UserContext);
Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle

The supplied PortletContext MUST refer to either a Producer Offered Portlet or a previously
cloned Consumer Configured Portlet. The initial state of the new Portlet MUST be equivalent tothe state of the Portlet referenced by the supplied handle. The PortletDescription for the
supplied portletHandle will apply to the newly cloned Portlet as well. In the case of a
Consumer Configured Portlet that pushes the Portlet’s persistent state to the Consumer, theportletState field of the returned PortletContext structure will supply that state. The new
portletHandle MUST be scoped by the registrationHandle in the supplied
RegistrationContext and be unique within this registration.

20

25

If a Producer chooses to push the persistent state of its Portlets to the Consumer, it is
RECOMMENDED that the portletHandle encode the supplied registrationHandle. In thiscase, it is also RECOMMENDED that the portletState encode the portletHandle so that
the Producer can do reasonable cross checks that it is receiving a consistent set of handles
and state.

30

The returned PortletContext contains both the portletHandle and portletState fields foruse in subsequent invocations on the configured Portlet. No relationship between the supplied
Portlet and the new Portlet is defined by this specification. The Consumer attempts to release
the new portletHandle by invoking destroyPortlets() when it is no longer needed.
If the Consumer has not registered, then the Consumer MUST invoke destroyPortlets() when
it would have deregistered, passing each portletHandle that would have been scoped by aregistration.

35

8.4 destroyPortlets() Operation
The Consumer MUST inform the Producer that a Consumer Configured Portlet will no longer
be used by invoking destroyPortlets() and MUST NOT consider a Portlet to have been
destroyed until destroyPortlets() has been successfully invoked for that Portlet.

40

DestroyPortletsResponse = destroyPortlets(RegistrationContext, portletHandles);Faults: Security.InconsistentParameters, Security.InvalidRegistration,
Interface.MissingParameters, Interface.OperationFailed

Web Services for Remote Portlets Specification

55

5

The supplied portletHandles is an array of type portletHandle, each of which theConsumer is informing the Producer it will no longer use. The Producer returns failures todestroy supplied portletHandles in the DestroyPortletsResponse structure. It is a choice of
the Producer’s implementation whether the resources related to the portletHandles are
immediately reclaimed or whether transient resources are allowed to timeout first. A Consumer
MUST NOT reference any of the supplied portletHandles after successfully invoking
destroyPortlets() and MAY reclaim resources related to the supplied portletHandles (e.g.
portletState).

8.5 setPortletProperties() Operation
10

15

20

25

30

The Portlet state in the previous operations was opaque to the Consumer (e.g. as
portletState). In addition, means are defined by which a Producer may publish information
about state in a Portlet-specific manner. This is enabled through Properties that are declaredin the metadata specific to a Portlet. Each property declaration includes a name and type(default = xsd:string) [A505][A507]. This operation enables the Consumer to interact withthis published portion of a Portlet’s state.
PortletContext = setPortletProperties(RegistrationContext, PortletContext, UserContext,
PropertyList);
Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle

Since setPortletProperties() is interacting only with the published portion of the Portlet’s state,
it is always safe for the Portlet to modify its state (i.e. equivalent to portletState set to“readWrite” for a performBlockingInteraction() invocation). The supplied set of propertychanges MUST be processed together. In particular, validation SHOULD only be done
considering the entire set, as partial updates could easily create an internally inconsistent set ofproperties. The storage of the update caused by applying the set of property updates SHOULD
only occur after the Producer/Portlet executes this validation. The Producer SHOULD serialize
invocations of setPortletProperties() for any one portletHandle. Note that changing aproperty’s value could impact the value of any of the Portlet’s properties.

8.6 getPortletProperties() Operation
This operation provides the means for the Consumer to fetch the current values of the
published Portlet’s properties. The intention is to allow a Consumer-generated user interface todisplay these for administrative purposes.
35

40

PropertyList = getPortletProperties(RegistrationContext, PortletContext, UserContext,
names);
Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle

The supplied names parameter is an array of strings each of which declares a property forwhich the Consumer is requesting its value. The returned PropertyList declares the current
values for these properties. If the Consumer does not pass a names parameter, the Producer /Portlet MUST treat this as a request to enumerate the properties of the Portlet.

Web Services for Remote Portlets Specification

56

8.7 getPortletPropertyDescription() Operation
This operation allows the Consumer to discover the published properties of a Portlet andinformation (e.g. type and description) that could be useful in generating a user interface forediting the Portlet’s configuration.
5

10

15

PortletPropertyDescriptionResponse = getPortletPropertyDescription(
RegistrationContext, PortletContext,
UserContext, desiredLocales);Faults: Security.AccessDenied, Security.InconsistentParameters,
Security.InvalidRegistration, Interface.MissingParameters,
Interface.OperationFailed, Interface.InvalidUserCategory,Interface.InvalidHandle

The modelDescription returned in the PortletPropertyDescriptionResponse structure is a
typed property view onto the portion of the Portlet’s persistent state that the user (referenced
through the userContext) is allowed to modify. While it is possible the set of properties canchange with time (e.g. the Portlet dynamically creates or destroys properties), Producers andPortlets SHOULD make the returned modelDescription as complete as possible.
When generating the PortletPropertyDescriptionResponse the Producer SHOULD use thedesiredLocales to control which locales are supplied for localized strings.

20

9 Security
25

Systems compliant with this specification will be exposed to the same security issues as otherweb service systems. For a representative summary of security concerns, refer to the Security
and Privacy Considerations document produced by the XML-Based Security Services Oasis
TC.

30

It is a goal within this specification to leverage standards efforts that address web services
security and to avoid defining mechanisms that will be redundant with those standards efforts.
These standards generally fall into two main categories: document-level mechanisms andtransport-level mechanisms.

35

The uses of document-level security mechanisms are not covered in this version of thespecification since several important standards (in particular, security policy declarations) are
not yet available. Producers and Consumers wishing to apply document-level security
techniques are encouraged to adhere to the mechanisms defined by WS-Security, SAML,
XML-Signature, XML-Encryption, and related specifications. It is anticipated that as the webservices security roadmap becomes more fully specified by standards, and support for thosestandards becomes widely available from infrastructure components, that these will play animportant role in future versions of this specification.

40

45

For this version of the specification, emphasis is placed on using transport-level security
standards (e.g. SSL/TLS) to address the security issues involved in Consumers invoking
Producers on behalf of End-Users. These only require that a Producer’s WSDL declare ports
for an HTTPS service entry point. Consumer’s can only determine that secure transport is
supported by parsing the URL for the service entry point.

Web Services for Remote Portlets Specification

579.1 Authentication of Consumer

5

Producer authentication of a Consumer may be achieved at the transport level through the useof client certificates in conjunction with SSL/TLS. Certificate provisioning by a Producer to a
Consumer happens outside the scope of this protocol, typically as part of establishing abusiness relationship between the Producer and Consumer.

9.2 Confidentiality & Message Integrity

10

SSL/TLS may be used to ensure the contents of messages are neither tampered with nor
decipherable by an unauthorized third party. Consideration needs to be given to both thecommunication between Producer and Consumer and communication between the End-Userclient and the Consumer.
For Producer - Consumer communication, the Producer declares the use of SSL/TLS in theservice’s WSDL by declaring an HTTPS service endpoint.

15

For Consumer – End-User client communication, the Consumer indicates in the MarkupParams
structure whether or not communication with the End-User is happening in a secure manner.
The Portlet can choose to change behavior based on this value, for example it may generate
markup that redirects the End-User to the equivalent secure page or throw a fault indicating
secure client communication are required.

20

9.3 Access control
A Consumer can implement access control mechanisms that restrict which End-Users may
access which Portlets and operations on those Portlets. Additionally, a Producer can implement
access control programmatically through the use of facilities such as an authenticated user
identity.

25

10 Markup
This section covers the issues related to Portlets generating markup that Consumers could
safely aggregate into a page and then properly process End-User interactions with the resulting
aggregated page [A301].

10.1 Encoding
30

35

The Consumer indicates to the Portlet the preferred character encoding, using themarkupCharacterSets field of the MarkupParams structure. It is up to the Portlet to generate
markup that complies with this encoding. The Portlet is allowed to generate its markup in either
the UTF-8 or UTF-16 character set encoding if it is unable to generate the requested characterset. If it is unable to generate markup in any of these character sets, the Portlet MUST return afault message to the Consumer. When the SOAP binding is in use, the nature of XML requiresthat the markup use the same character set as the XML response message.

10.2 URL Considerations
40

As part of its markup, a Portlet will often need to create URLs that reference the Portlet itself.
When an End-User activates such an URL, by clicking a link or submitting a form, the result
should be a new invocation targeted to the Portlet. This section describes the different
possibilities for how the Portlet can encode these “portlet URLs” in its markup.

Web Services for Remote Portlets Specification

58

The portlet URLs embedded in a markup fragment often can not (or should not) be direct links
to the Producer for a number of reasons:•

URLs the Portlet writes in its markup will be invoked or accessed by the End-User
operating on the client. In the general case however it is only guaranteed that the client
has direct access to the Consumer; the Producer may be shielded from the client via afirewall. So the Consumer needs to intercept URLs and route them to the Producer[A103].

•The Consumer may want to intercept URLs to perform additional operations, enrich therequest with context information or do some book keeping.

•

The client might not be able to directly invoke the Producer, e.g. if the client is a useragent that cannot issue SOAP requests to the Producer but can only talk HTTP to theConsumer. In this case the Consumer must translate the request into the correct
protocol.

5

10

15

20

This implies that portlet URLs must be encoded so that the Consumer intercepts them and reroutes them to the correct Portlet at the Producer, including the proper context. Because thesame Portlet can be instantiated more than once in a single aggregated page, portlet URLs will
have to allow the Consumer to track the Portlet to which the request is targeted. The problem isthat the Producer requires Consumer-dependent information to write such a link. In principle
there exist two options to make a portlet URL point back to the Consumer and consist of all
information necessary for the Consumer to properly process an activation of the URL:•

The Consumer can pass information on its context to the Portlet. The Portlet exploits
this information during URL encoding so the resulting URL can be passed without
further modification to the client. The advantages of this technique are efficiency andexploitation of these settings, even in client-side scripting. The disadvantages include
that the Portlet will not be able to serve static content as the content depends on
Consumer runtime settings and that the resulting markup might be less cacheable by
the Consumer.

•

The Portlet can use a special syntax to encode portlet URLs. It is then the task of theConsumer to detect portlet URLs in the markup and modify them according to its
requirements. The markup generated by the Portlet is now Consumer-independent,
allowing the Portlet to exploit caching mechanisms or even to serve static content.
However, the Consumer will be more complex, as it needs to parse the markup to
locate and rewrite portlet URLs, and require additional processing time. Consumers
can minimize this impact on performance by using efficient encoding and parsing
mechanisms (for example, the Boyer-Moore algorithm17).

25

30

35

As there is no clear advantage to either technique, both styles of portlet URL encoding aresupported (see sections 10.2.1 and 10.2.2). This facilitates the capabilities both of the Producer
and the Consumer with regards to the ability to adapt the generated markup and requires thatthe following semantics be followed:
40

1. If a Portlet’s metadata declares it is willing to process URL templates, then the Consumer
supplies templates for the Portlet to use.
2. As the Portlet writes URLs into the markup it MUST encode them based on the mime
type. For example, XML based markup requires that all ‘&’ characters have to be
encoded as “&amp;”.

45

3. If a Portlet is unable to completely write the portlet URLs for its markup, it MUST set therequiresUrlRewriting flag in the returned MarkupContext structure to “true”.
4. If the requiresUrlRewriting flag in the MarkupContext structure is “true”, then theConsumer parses the returned markup and rewrites URLs conforming to the definitions in
Section 9 of this specification.

17

http://www.cs.utexas.edu/users/moore/best-ideas/string-searching/

Web Services for Remote Portlets Specification

59

5

10

Note: In principle it would not be necessary to mark portlet URLs in a special way. The
Consumer could always analyze the markup semantically and syntactically, detect portlet URLs
and rewrite them. This approach however would be very difficult and time consuming to
implement for the Consumer, for reasons including that such a rewriting algorithm would be
dependent on the markup type and version. Therefore both the Consumer and the Producer
URL writing scenarios are introduced for convenience.
Portlets MUST adopt the following convention for including non-ASCII characters within portlet
URLs in order to comply with W3C recommendations.
1. Represent each character in UTF-8 (see [RFC2279]) as one or more bytes.
2. Escape these characters with the URI escaping mechanism (i.e., by converting each byte
to %HH, where HH is the hexadecimal notation of the character value).

15

20

25

This procedure results in a syntactically legal URI (as defined in RFC1738, section 2.2 or
RFC2141, section 2) that is independent of the character encoding18 to which the document
carrying the URI may have been transcoded.
Since the values a Portlet provides will appear as either an URL parameter value or as part ofthe path of an URL, these values it MUST be strictly encoded (i.e. “&”, “=“, “/”, and “?” need tobe url-escaped) so that special URL characters do not invalidate the processing of theenclosing URL.
When URL activation occurs, the Consumer MUST process all mode and window state change
requests and either honor and reject them prior to invoking the operation indicated by the URL.
If the requested mode or window state is for a value that is either invalid or unavailable, theConsumer SHOULD leave the current value unchanged.

10.2.1 Consumer URL Rewriting
30

35

All portlet URLs (i.e. those the Consumer needs to rewrite) are demarcated in the markup by atoken (wsrp-rewrite) both at the start (with a “?” appended to clearly delimit the start of thename/value pairs) and end (proceeded by a “/” to form the end token) of the URL declaration.
The Consumer will have to locate the start and end token in the markup stream and use theinformation between the tokens to rewrite the portlet URL correctly. Details on this URL writing
process are Consumer-specific and out of scope for this specification. The content between
this pair of tokens follows the pattern of a query string (name/value pairs separated by “&”characters) with several well-known “portlet URL parameter” names specifying the information
the Consumer needs in order to both correctly rewrite the URL and then process it when an
End-User activates it. This results in an portlet URL declaration of the form:
wsrp-rewrite?wsrp-urlType=value&name1=value1&name2=value2 .../wsrp-rewrite

40

The Consumer is NOT REQUIRED to process URLs not conforming to this format and MAY
choose to pass them unchanged, replace them with error text, do a best effort processing orinvalidate the entire markup fragment. The Consumer is NOT REQUIRED to process escapedcharacters in parameter names or values, but rather MAY pass them unchanged to either theuser-agent (during URL rewriting) or the Producer (during processing of an activated URL).

18

http://www.w3.org/TR/html40/charset.html - doc-char-set

Web Services for Remote Portlets Specification

60

The following well-known portlet URL parameter names (e.g. replacing “wsrp-urlType=value”,“name1” and “name2” above) are defined:

10.2.1.1
5

wsrp-urlTypeThis parameter MUST be specified first when using the Consumer URL rewriting template andthe value selected from the following definitions. Well-known portlet URL parameter names thatare valid for only one wsrp-urlType are described relative to that wsrp-urlType while theremainder are described later. The following values are defined for wsrp-urlType:10.2.1.1.1 wsrp-urlType = blockingAction
10

Activation of the URL will result in an invocation of performBlockingInteraction() on the
Portlet that generated the markup. All form parameters, submitted as query string
parameters using the HTTP GET method, that are not used to encode parameters definedby this specification MUST be passed to performBlockingInteraction() as
formParameters.

10.2.1.1.2 wsrp-urlType = render
15

20

Activation of the URL will result in an invocation of getMarkup(). This mechanism permits a
Portlet’s markup to contain URLs, which do not involve changes to local state, to avoid theoverhead of two-step processing by directly invoking getMarkup(). The URL MAY specify a
wsrp-navigationalState portlet URL parameter, whose value the Consumer MUST
supply in the navigationalState field of the MarkupParams structure. If there is no such
portlet URL parameter, the Consumer MUST NOT supply a value for this field.

10.2.1.1.3 wsrp-urlType = resource

25

Activation of the URL will result in the Consumer acting as a gateway to the underlying
resource, possibly in a cached manner, and returning it to the user-agent. The URL for the
resource (including any query string parameters) is encoded as the value of the wsrp-url
parameter. When a portlet URL specifies “resource” for the wsrp-urlType portlet URL
parameter, both the wsrp-url and wsrp-requiresRewrite portlet URL parameters MUST
also be specified. If the Portlet needs to share data with the referenced resource, it can
exploit the cookie support defined in section 10.4.

10.2.1.1.3.1
30

35

wsrp-urlThis parameter provides the actual URL to the resource. Note that this needs to be an
absolute URL as the resource fetch will have no base for use in fetching a relative URL.
Also note that since this resource URL will appear as a parameter value, it has to bestrictly encoded (i.e. “&”, “=“, “/”, and “?” need to be url-escaped) so that special URL
characters do not invalidate the processing of the enclosing URL. Consumers areencouraged to use the same communication style (e.g. HTTP Get or Post) for retrieving
the resource as was used in requesting the resource by the user-agent.

Web Services for Remote Portlets Specification

61

10.2.1.1.3.2

5

10

wsrp-requiresRewrite

This boolean informs the Consumer that the resource needs to be parsed for URL
rewriting. Normally this means that there are names that will be cross-referenced
between the markup and this resource (e.g. JavaScript references). Note that this means
the Consumer needs to deal with rewriting unique “namespaced” names in a set of
documents, rather than treating each document individually. Processing such resourcesin a manner that allows caching of the resulting resource by the End-User’s user-agent
can improve the performance of the aggregated page for the End-User. In particular,
Consumers can process namespace rewriting by using a prefix that is unique to theuser/Portlet pair provided any such prefix is held constant for the duration of use within
the user’s session with the Consumer of any one Portlet.

10.2.1.1.4 wsrp-urlType = namespace

15

20

This tells the Consumer that the portlet “URL” contains a name that needs to be unique on
the aggregated page (e.g. a form field’s name or the name of a JavaScript method). While
this is not technically a URL, providing this functionality in this manner limits theperformance impacts of Consumer parsing to a single pass of the markup. The actualname that needs to be rewritten is encoded in the wsrp-token parameter which MUST be
supplied whenever wsrp-urlType has a value of “namespace”. See section 10.3 for moredetails on namespacing.

10.2.1.1.4.1

wsrp-token

This parameter provides the actual token that is to be namespaced. The wsrp-token
portlet URL parameter MUST only be used in URLs where the wsrp-urlType portlet URL
parameter has a value of “namespace”.

10.2.1.2
25

The value of this portlet URL parameter defines the navigational state the Consumer MUST
send to the Producer when the URL is activated. If this parameter is missing, the Consumer
MUST NOT supply the navigationalState field of the MarkupParams.

10.2.1.330

wsrp-mode

Activating this URL includes a request to change the mode parameter in MarkupParams into themode specified as the value for this portlet URL parameter. The value for wsrp-mode MUST be
one of the modes detailed in section 6.8 or a custom mode the Consumer specified as
supported during registration. The wsrp-mode portlet URL parameter MAY be used whenever
the wsrp-urlType portlet URL parameter has a value of “blockingAction” or “render”.

10.2.1.540

wsrp-interactionStateThe value of this portlet URL parameter defines the interaction state the Consumer MUST send
to the Producer when the URL is activated. If this parameter is missing, the Consumer MUSTNOT supply the interactionState field of the InteractionParams structure.

10.2.1.4

35

wsrp-navigationalState

wsrp-windowState

Activating this URL includes a request to change the windowState parameter in MarkupParams
into the window state specified as the value for this portlet URL parameter. The value for wsrpwindowState MUST be one of the values detailed in section 6.9 or a custom window state theConsumer specified as supported during registration. The wsrp-windowState portlet URL
parameter MAY be used whenever the wsrp-urlType portlet URL parameter has a value of“blockingAction” or “render”.

Web Services for Remote Portlets Specification

62

10.2.1.6

wsrp-fragmentID

This portlet URL parameter specifies the portion of an URL that navigates to a place within adocument.

10.2.1.7
5

10

wsrp-secureURL

The value for the wsrp-secureURL is a boolean indicating whether the resulting URL MUST involve
secure communication between the client and Consumer, as well as between the Consumer and Producer.
The default value of this boolean is “false”. Note that the Consumer’s aggregated page MUST be secure if
any of the Portlets whose content is being displayed on the page have indicated the need for securecommunication for their current markup.

10.2.1.8

URL examples

Here are some examples of portlet URLs following this format:•

Load a resource http://test.com/images/test.gif:o wsrp-rewrite?wsrp-urlType=resource&wsrpurl=http%3A%2F%2Ftest.com%2Fimages%2Ftest.gif&wsrprequiresRewrite=true/wsrp-rewrite

15•

Declare this token as needing namespacing:o wsrp-rewrite?wsrp-urlType=namespace&wsrp-token=myFunc/wsrp-rewrite•

Declare a secure interaction back to the Portlet:o wsrp-rewrite?wsrp-urlType=blockingAction&wsrp-secureURL=true&wsrpnavigationalState=a8h4K5JD9&interactionState=fg4h923mdk/wsrp-rewrite

20•

Request the Consumer render the Portlet in a different mode and window state:o wsrp-rewrite?wsrp-urlType=render&wsrp-mode=help&wsrpwindowState=maximized/wsrp-rewrite

10.2.2 Producer URL Writing
25

To enable Producer URL writing, several templates are defined by which the Consumer
indicates how it needs portlet URLs formatted in order to process them properly. These all takethe form of a simple template, for example:
http://www.Consumer.com/path/{wsrp-urlType}?mode={wsrp-mode}&…

30

35

40

45

The definition of the content of this template is completely up to the Consumer. It may consistof zero or more replacement tokens. These tokens are enclosed in curly braces (i.e. “{” and “}”)and contain the name of the portlet URL parameter that should be replaced. This replacement
includes the curly braces, namely; “{wsrp-urlType}” becomes “render” when that is the desired
URL type. All content outside the {} pairs MUST be treated by the Producer/Portlet as
constants the Consumer needs to receive when the portlet URL is activated. The list of defined
portlet URL parameter names matches those in section 10.2.1 with the addition of thosespecified in section 10.2.2.9.
Portlets dynamically computing portlet URLs in the user-agent environment (e.g. in JavaScript)
need to take into account the distributed nature of preparing and processing portlet URLs. The
Consumer’s template might not directly produce a valid URL, but may be such that theConsumer further processes the portlet URL for its own purposes (e.g. adds data it needs
when the portlet URL is activated which has not been supplied to the Producer). As a result,the only safe means to accommodate this computation of dynamic URLs is to store thetemplate(s) whole in the markup and then use this template directly when computing the
dynamic portlet URL.
Web Services for Remote Portlets Specification

63

5This specification defines a Templates structure that supplies values for the set of defined
templates. The Consumer supplies these templates for Portlets specifying
doesUrlTemplateProcessing as “true”. Portlets also specifying templatesStoredInSession
as “true” enable the Consumer to only send these until the Producer returns a sessionID. The
following describe in more detail the usage of the fields from the Templates structure.

10.2.2.1

10

blockingActionTemplate

Activation of the URL will result in an invocation of performBlockingInteraction(). The
Consumer MUST integrate placeholders for at least the portlet URL parameters wsrpnavigationalState, wsrp-interactionState, wsrp-mode and wsrp-windowState in its
template and SHOULD integrate placeholders for the other portlet URL parameters defined inthis specification.

10.2.2.2

secureBlockingActionTemplate

secureBlockingActionTemplate is equivalent to blockingActionTemplate, but using

15

secure communication.

10.2.2.3

renderTemplate

Activation of the URL will result in an invocation of getMarkup(). The Consumer MUST
integrate placeholders for at least the portlet URL parameters wsrp-navigationalState,wsrp-mode and wsrp-windowState in its template.
20

10.2.2.4

secureRenderTemplate

secureRenderTemplate is equivalent to renderTemplate, but using secure communication.

10.2.2.5
25

resourceTemplate

Activation of the URL will result in the Consumer fetching the underlying resource, possibly in acached manner, and returning it to the End-User. The Consumer MUST integrate placeholders
for at least the portlet URL parameters wsrp-url and wsrp-requiresRewrite to allow thePortlet to place the address of the URL. If the Portlet needs to share data with the referenced
resource, it can exploit the cookie support defined in section 10.4.

10.2.2.6

secureResourceTemplate

ResourceTemplate is equivalent to ResourceTemplate, but using secure communication.

30

35

10.2.2.7

defaultTemplate

This is the template whose value is to be used as the default value for any non-secure template
whose value is not supplied. Consumers not supplying all the other non-secure templates
MUST set a value for this template. Since this may become the value for an action oriented
template, the Consumer SHOULD integrate placeholders for at least the portlet URL
parameters wsrp-navigationalState, wsrp-interactionState, wsrp-mode and wsrpwindowState in this template.

Web Services for Remote Portlets Specification

6410.2.2.8

5This is the template whose value is to be used as the default value for any secure template (i.e.
those with names beginning with “secure”) whose value is not supplied. Consumers not
supplying all the other secure templates MUST set a value for this template. Since this may
become the value for an action oriented template, the Consumer SHOULD integrate
placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrpinteractionState, wsrp-mode and wsrp-windowState in this template.

10.2.2.9
10

secureDefaultTemplate

Portlet URL parameters

The following portlet URL parameters are defined for the purpose of enabling a Consumer’s
templates to be generic to a Producer. If the Consumer includes wsrp-portletHandle, wsrpuserContextKey, wsrp-portletInstanceKey or wsrp-sessionID in a template, Producer
written URLs based on that template MUST replace the specified portlet URL parameter withthe value the Consumer separately supplied in a data field.
Portlet URL parameter name

Structure nameField namewsrp-portletHandle

PortletContext

portletHandle

wsrp-userContextKey

UserContext

userContextKey

wsrp-portletInstanceKey

RuntimeContext

portletInstanceKey

wsrp-sessionID

RuntimeContext

sessionID10.2.3 BNF Description of URL formats
15

ConsumerURL = BeginToken UrlTypePair NameValuePairs EndToken
BeginToken = “wsrp-rewrite?”
EndToken = “/wsrp-rewrite”
UrlTypePair = “wsrp-urlType” “=” UrlType
UrlType = “blockingAction” | “render” | “resource” | “namespace”

20

NameValuePairs = (“&” NameValuePair)*
NameValuePair = TextPair | BooleanPair
TextPair = TextName “=” Text
TextName = “wsrp-navigationalState” | “wsrp-interactionState” | “wsrp-mode” |“wsrp-windowState” | “wsrp-url” | “wsrp-token” | “wsrp-fragmentID”

25

Text = <any URL-encoded textual characters>
BooleanPair = BooleanName “=“ BooleanValue
BooleanName = “wsrp-secureURL” | “wsrp-requiresRewrite”
BooleanValue = (“true” | “false”)

30

ProducerURLTemplate = (Text* ReplacementToken*)*ReplacementToken = “{” ParameterName “}”ParameterName = TextName | BooleanName | “wsrp-urlType” | “wsrpportletHandle” | “wsrp-userContextKey” | “wsrp-portletInstanceKey” | “wsrpsessionID”

Web Services for Remote Portlets Specification

6510.2.4 Method=get in HTML forms

5

10

User-Agents often throw away any query string from the URL indicated with the form’s action
attribute when generating the URL they will activate when the form’s method is “get”. This is thesimplest means for them to generate a valid query string. The difficulty this causes is that
Consumer’s often prefer to store the information they will use when a portlet URL is activatedas query string parameters. As a result, Portlets that include HTML forms with method=get intheir markup MUST specify usesMethodGet as “true” in their PortletDescription.
Consumers choosing to use such Portlets need to format their portlet URLs such that portlet
URL activations are processed correctly, regardless of whether Consumer or Producer URL
writing is in use.

10.3 Namespace Encoding

15

20

25

30

Aggregating multiple Portlets from different sources can potentially result in naming conflicts forvarious types of elements: named attributes, JavaScript functions and variables, etc. Tokens
needing uniqueness on the aggregated page MUST be encoded to a Portlet-instance specificnamespace [A301]. The Portlet MAY do this by prefixing the name of the resource with thenamespacePrefix from the RuntimeContext structure. We note that the JavaScript examples
exclude the possibility of starting such prefixes with a numerical character.
Consumer URL and form processing has been designed so that namespace prefixing is notneeded to qualify portlet URL parameters, portlet form parameters, or resource URL
parameters. This allows Consumers to avoid unnecessary processing when dispatching client
requests. Portlets choosing to namespace such elements MUST process these parameterswith their namespace prefix attached as Consumers MUST NOT remove any prefixes. We
would note that many things Producers and Portlets could namespace, such as field names inHTML forms, are not required to be unique and therefore are preferably not namespaced as
this adds processing burden to generate and remove the namespacing. This likely has an
impact on client side code that may currently use such items to locate items on the page. In thecase of field names within HTML forms, we would note that namespacing an id attribute andusing it to locate the field provides the desired uniqueness within the aggregated environment
without introducing a processing burden as would be caused if the name attribute werenamespaced instead.
Similar to the case of URL rewriting, two options exist to obtain a namespace prefix.

10.3.1 Consumer Rewriting
35

40

The Portlet uses the static, predefined method (section 10.2.1) to denote tokens that need anamespace prefix. The Consumer parses the markup fragment to locate these tokens andreplace them with a namespaced token unique in the context of the page aggregation. This
namespaced token MUST be the same for all occurrences of the token in the set of documents
processed for one instance of the Portlet while assembling the aggregated page. This is doneusing the same method as Consumer URL rewriting and is described in section 10.2.1. It is
expected that the length this method adds to names might make it unwieldy to content authors,
but the expectation that tooling/runtime support can alleviate most of this burden led to reusing
this singular technique for the Consumer parsing/rewriting the markup.

10.3.2 Producer Writing
45

The Portlet uses the namespacePrefix provided by the Consumer in the RuntimeContext
structure to prefix these tokens in its markup.

Web Services for Remote Portlets Specification

6610.4 Using Resources

5

There are times when a resource which a portlet references needs access to data relative tothe interactions of the End-User with the Portlet. While this version of the specification does notseek to address this need in a comprehensive manner, we note that a solution already exists
for the common case of HTTP being the protocol for communication. Producers can set
cookies with the needed data which the Consumer will then process, using the cookie rules
established by RFC210919, relative to forwarding these to resources referenced by the Portlet.

10.5 Markup Fragment Rules
10

15

Because the Consumer aggregates the markup fragments produced by Portlets into a single
page, some rules and limitations are needed to ensure the coherence of the resulting page tobe displayed to the End-User. For efficiency reasons, Consumers are not required to validate
the markup fragments returned by the Portlet. So in order to be aggregated, the Portlet’smarkup needs to conforms to the following general guidelines [A300][A302].
The disallowed tags listed below are those tags that impact other Portlets or may even breakthe entire aggregated page. Inclusion of such a tag invalidates the whole markup fragment,
which the Consumer MAY replace with an error message.

10.5.1 HTML10.5.1.1
20

Disallowed Tags

Since the Consumer may implement its aggregation in many ways, including using frames,
some Consumers may actually support these disallowed tags. However, in order to be a
conforming Portlet, a Portlet MUST NOT use the tags <body>, <frame>, <frameset>, <head>,<html>, and <title>.

10.5.1.2

Other Tags

25

There are some tags that are specifically prohibited by the HTML specification from occurringoutside the <head> of the document. However, user-agent implementations offer varying
levels of support. For example, current versions of Internet Explorer and Netscape Navigator
both support the style tag anywhere within the document.

30

It is up to the Portlet developer to decide when using such tags is appropriate. Tags fitting thisdescription include <base>, <link>, <meta>, and <style>.

10.5.2 XHTML
10.5.2.1
35

Disallowed Tags

Since the Consumer may implement its aggregation in many ways, including using frames,
some Consumers may actually support these disallowed tags. However, in order to be a
conforming Portlet, a Portlet MUST NOT use the tags <body>, <head>, <html>, and <title>.

19

http://www.ietf.org/rfc/rfc2109.txt

Web Services for Remote Portlets Specification

6710.5.2.2

5

Other Tags

There are some tags that are specifically prohibited by the XHTML specification from occurringoutside the <head> of the document. However, user-agent implementations offer varying
levels of support. For example, current versions of Internet Explorer and Netscape Navigator
both support the style tag anywhere within the document.
It is up to the Portlet developer to decide when using such tags is appropriate. Tags fitting thisdescription include <base>, <link>, <meta>, and <style>.

10.5.3 XHTML Basic
10

10.5.3.1

Disallowed Tags

Since the Consumer may implement its aggregation in many ways, including using frames,
some Consumers may actually support these disallowed tags. However, in order to be a
conforming Portlet, a Portlet MUST NOT use the tags <body>, <head>, <html>, and <title>.

10.5.3.2

Other Tags

15

There are some tags that are specifically prohibited by the XHTML Basic specification fromoccurring outside the <head> of the document. However, user-agent implementations offer
varying levels of support. For example, current versions of Internet Explorer and Netscape
Navigator both support the style tag anywhere within the document.

20

It is up to the Portlet developer to decide when using such tags is appropriate. Tags fitting thisdescription include <base>, <link>, <meta>, and <style>.

10.6 CSS Style Definitions
25

30

One of the goals of an aggregated page is a common look-and-feel across the Portlets
contained on that page. This not only affects the decorations around the Portlets, but also theircontent. Using a common CSS style sheet for all Portlets, and defining a set of standard styles,
provides this common look-and-feel without requiring the Portlets to generate Consumerspecific markup. Portlets SHOULD use the CSS style definitions from this specification in orderto participate in a uniform display of their content by various Consumers. For markup types that
support CSS stylesheets, Consumers MUST supply a CSS stylesheet to the End-User’s agent
with definitions for the classes defined in section 10.6 of this specification.
This section defines styles for a variety of logical units in the markup.

10.6.1 Links (Anchor)
35

A custom CSS class is not defined for the <a> tag. The Portlet should use the default classes
when embedding anchor tags.

Web Services for Remote Portlets Specification

6810.6.2 Fonts
The font style definitions affect the font attributes only (i.e. font face, size, color, style, etc.).
Style

Description

Exampleportlet-font

Font attributes for the “normal” fragment font. Used forthe display of non-accentuated information.

NormalText

portlet-font-dim

Font attributes similar to the portlet-font but the color islighter.

Dim Text

If a Portlet author wants a certain font type to be larger or smaller, they should indicate thisusing a relative size.
5

Example1: <div class="portlet-font" style="font-size:larger">Important information</div>
Example1: <div class="portlet-font-dim" style="font-size:80%">Small and dim</div>

10.6.3 Messages
Message style definitions affect the rendering of a paragraph (i.e. alignment, borders,background color, etc.) as well as text attributes.

10

Style

Description

Exampleportlet-msg-status

Status of the current operation.

Progress: 80%

portlet-msg-info

Help messages, general
additional information, etc.

Info about

portlet-msg-error

Error messages.

Portlet not available

portlet-msg-alert

Warning messages.

Timeout occurred, try again
later

portlet-msg-success

Verification of the successful
completion of a task.

Operation completed
successfully

10.6.4 Sections
Section style definitions affect the rendering of markup sections such as div and span (i.e.
alignment, borders, background color, etc.) as well as their text attributes.
Style

Description

portlet-section-header

Section header

portlet-section-bodyNormal text

portlet-section-alternate

Text in every other row in the section

portlet-section-selected

Text in a selected range

portlet-section-subheader

Text of a subheading

portlet-section-footer

Section footer

portlet-section-text

Text that belongs to the section but does not fall in one of theother categories (e.g. explanatory or help text that is
associated with the section).

Web Services for Remote Portlets Specification

69

10.6.5 Tables
Table style definitions affect the rendering (i.e. alignment, borders, background color, etc.) as
well as their text attributes.
Style

Description

portlet-table-header

Table header

portlet-table-bodyNormal text in a table cell

portlet-table-alternate

Text in every other row in the table

portlet-table-selected

Text in a selected cell range

portlet-table-subheader

Text of a subheading

portlet-table-footer

Table footer

portlet-table-text

Text that belongs to the table but does not fall in one of theother categories (e.g. explanatory or help text that is
associated with the table).

10.6.6 Forms
5

Form styles define the look-and-feel of the elements in an HTML form.
Style

Description

portlet-form-label

Text used for the descriptive label of the whole form (not thelabels for fields.

portlet-form-input-field

Text of the user-input in an input field.

portlet-form-button

Text on a button

portlet-icon-label

Text that appears beside a context dependent action icon.

portlet-dlg-icon-label

Text that appears beside a “standard” icon (e.g. Ok, or Cancel)

portlet-form-field-label

Text for a separator of fields (e.g. checkboxes, etc.)

portlet-form-field

Text for a field (not input field, e.g. checkboxes, etc)
Portlet.portt-form-field-label.portlert-form-label

Enter Option.portlet-form-input-field
Enter password.portlet-form-field

Check an option
Clere

Web Services for Remote Portlets Specification.portlet-form

70

10.6.7 Menus
5

Menu styles define the look-and-feel of the text and background of a menu structure. This
structure may be embedded in the aggregated page or may appear as a context sensitive
popup menu.
Style

Description

portlet-menu

General menu settings such as
background color, margins, etc

portlet-menu-item

Normal, unselected menu item.

portlet-menu-item-selected

Selected menu item.

portlet-menu-item-hover

Normal, unselected menu item when themouse hovers over it.

portlet-menu-item-hover-selected

Selected menu item when the mouse
hovers over it.

portlet-menu-cascade-item

Normal, unselected menu item that has
sub-menus.

portlet-menu-cascade-item-selected

Selected sub-menu item that has submenus.

portlet-menu-description

Descriptive text for the menu (e.g. in ahelp context below the menu)

portlet-menu-caption

Menu caption
Portlet.portlet-menu-item-selected.portlet-menu-caption

Portlet Menu

.portlet-menu-item

Edit
ConfigMisc.portlet-menu-cascade-item

Some text that
explains this menu

SubItem1
SubItem1.portlet-menu-description

11 User Information
10

This specification provides a mechanism for Portlets to use End-User information as a meansfor personalizing behavior to the current user [A600][A606]. A standard set of user attributes
has been derived from P3P User Data. Extensibility is supported in both directions; theConsumer indicates to the Producer during registration what set of user profile extensions it
supports, and a Portlet’s metadata declares what user profile items it uses (including any
extended user profile items). The following table maps the nested profile structures to
userProfileItems:

Profile Name

Structure 1

name/prefix

PersonName

Web Services for Remote Portlets Specification

Structure 2

Structure 3

Field Name
prefix71

name/given

PersonName

given

name/family

PersonName

familyname/middle

PersonName

middlename/suffix

PersonName

suffixname/nickname

PersonName

nickname

bDate

bDate

gendergenderemployerInfo/employer

EmployerInfo

employer

employerInfo/department

EmployerInfo

department

employerInfo/jobtitle

EmployerInfo

jobtitle

homeInfo/postal/nameContact

PostalnamehomeInfo/postal/street

Contact

PostalstreethomeInfo/postal/city

Contact

Postalcity

homeInfo/postal/stateprov

Contact

Postalstateprov

homeInfo/postal/postalcode

Contact

Postalpostalcode

homeInfo/postal/country

Contact

Postalcountry

homeInfo/postal/organization

Contact

Postalorganization

homeInfo/telecom/telephone/intcode

Contact

Telecom

TelephoneNum

intcodehomeInfo/telecom/telephone/loccode

Contact

Telecom

TelephoneNumloccodehomeInfo/telecom/telephone/number

Contact

Telecom

TelephoneNum

numberhomeInfo/telecom/telephone/ext

Contact

Telecom

TelephoneNum

ext

homeInfo/telecom/telephone/comment

Contact

Telecom

TelephoneNum

comment

homeInfo/telecom/fax/intcode

Contact

Telecom

TelephoneNum

intcodehomeInfo/telecom/fax/loccode

Contact

Telecom

TelephoneNumloccodehomeInfo/telecom/fax/number

Contact

Telecom

TelephoneNum

numberhomeInfo/telecom/fax/ext

Contact

Telecom

TelephoneNum

ext

homeInfo/telecom/fax/comment

Contact

Telecom

TelephoneNum

comment

homeInfo/telecom/mobile/intcode

Contact

Telecom

TelephoneNum

intcodehomeInfo/telecom/mobile/loccode

Contact

Telecom

TelephoneNumloccodehomeInfo/telecom/mobile/number

Contact

Telecom

TelephoneNum

numberhomeInfo/telecom/mobile/ext

Contact

Telecom

TelephoneNum

ext

homeInfo/telecom/mobile/comment

Contact

Telecom

TelephoneNum

comment

Web Services for Remote Portlets Specification72

homeInfo/telecom/pager/intcode

Contact

Telecom

TelephoneNum

intcodehomeInfo/telecom/pager/loccode

Contact

Telecom

TelephoneNumloccodehomeInfo/telecom/pager/number

Contact

Telecom

TelephoneNum

numberhomeInfo/telecom/pager/ext

Contact

Telecom

TelephoneNum

ext

homeInfo/telecom/pager/comment

Contact

Telecom

TelephoneNum

comment

homeInfo/online/email

Contact

Onlineemail

homeInfo/online/uri

Contact

OnlineuribusinessInfo/postal/nameContact

PostalnamebusinessInfo/postal/street

Contact

PostalstreetbusinessInfo/postal/city

Contact

PostalcitybusinessInfo/postal/stateprov

Contact

Postalstateprov

businessInfo/postal/postalcode

Contact

Postalpostalcode

businessInfo/postal/country

Contact

PostalcountrybusinessInfo/postal/organization

Contact

Postalorganization

businessInfo/telecom/telephone/intcode

Contact

Telecom

TelephoneNum

intcodebusinessInfo/telecom/telephone/loccode

Contact

Telecom

TelephoneNumloccodebusinessInfo/telecom/telephone/number

Contact

Telecom

TelephoneNum

numberbusinessInfo/telecom/telephone/ext

Contact

Telecom

TelephoneNumext

businessInfo/telecom/telephone/comment

Contact

Telecom

TelephoneNum

comment

businessInfo/telecom/fax/intcode

Contact

Telecom

TelephoneNum

intcodebusinessInfo/telecom/fax/loccode

Contact

Telecom

TelephoneNumloccodebusinessInfo/telecom/fax/number

Contact

Telecom

TelephoneNum

numberbusinessInfo/telecom/fax/ext

Contact

Telecom

TelephoneNumext

businessInfo/telecom/fax/comment

Contact

Telecom

TelephoneNum

comment

businessInfo/telecom/mobile/intcode

Contact

Telecom

TelephoneNum

intcodebusinessInfo/telecom/mobile/loccode

Contact

Telecom

TelephoneNumloccodebusinessInfo/telecom/mobile/number

Contact

Telecom

TelephoneNum

numberbusinessInfo/telecom/mobile/ext

Contact

Telecom

TelephoneNumext

businessInfo/telecom/mobile/comment

Contact

Telecom

TelephoneNum

comment

businessInfo/telecom/pager/intcode

Contact

Telecom

TelephoneNum

intcodebusinessInfo/telecom/pager/loccode

Contact

Telecom

TelephoneNumloccodebusinessInfo/telecom/pager/number

Contact

Telecom

TelephoneNum

numberWeb Services for Remote Portlets Specification73

businessInfo/telecom/pager/ext

Contact

Telecom

TelephoneNumext

businessInfo/telecom/pager/comment

Contact

Telecom

TelephoneNum

comment

businessInfo/online/email

Contact

Onlineemail

businessInfo/online/uri

Contact

Onlineuri

Portlets that need access to user information declares in its metadata the specific user profile
fields it needs using the names specified above.

5

Consumers supplying additional custom profile fields are encourage to publish a similar
mapping between userProfileItems and the custom fields.

11.1 Passing User Information
User information can be supplied to the Producer when a Consumer invokes certain
operations. A Consumer SHOULD provide the specific fields the Portlet declared it needs,
unless the information is not available or is restricted by policy (e.g. privacy policy).
1011.2 User Identity
Mechanisms that support federation of user identity between web services systems are definedin other specifications, such as WS-Security and SAML. If a Consumer and Producer need toshare a common identity for an End-User, it is recommended that compliance with thesestandards be the means to passing the required information.

15

20

It is anticipated that some Portlets will interact with one or more back-end applications that
require a user identity for the End-User. If the user identity required by the back-end application
is not the same as that authenticated or otherwise supplied by the Consumer, the Portlet canrequest the End-User to provide the necessary information (preferably using secure transport)
for use with the back-end application via markup interactions (e.g. display a form that prompts
for a user identity and any security tokens (such as a password) for the back-end system).

Web Services for Remote Portlets Specification74

12 Constants
Type

Value

DescriptionMode

wsrp:view

Portlet is expected to render markup reflecting its current state.

Mode

wsrp:edit

Portlet is expected to render markup useful for End-Usercustomization.

Mode

wsrp:help

Portlet is expected to render markup useful for helping an EndUser understand the Portlet’s operation.

Mode

wsrp:preview

Portlet is expected to render markup representative of its
configuration, as this might be useful to someone testing a pagelayout.

Windowstate

wsrp:normal

The Portlet is sharing space with other Portlets and should
restrict its consumption of space accordingly.

Windowstate

wsrp:minimized

The Portlet, though still aggregated on the page, is expected torestrict its consumption of space to a bare minimum.

Windowstate

wsrp:maximized

The Portlet is being offered significantly more that the normal
share of the space available to Portlets on the Consumer’s
aggregated page.

Windowstate

wsrp:solo

The Portlet is the only Portlet being rendered on the Consumer’s
aggregated page.

13 Fault Messages
5

In addition to generic fault messages that may be generated by the web service stacks of theConsumer and/or Producer, a variety of messages specific to this protocol are defined. WSDL
defines fault codes to be strings using “.” as a delimiter to scope the error codes. The following
are defined for constructing a WSRP error code within the same namespace as used for the
rest of the types defined by this specification:
Top Level

Specific CodeDescription

Security

AccessDenied

Policy has denied access. This may be related to theConsumer’s registration.

Security

InconsistentParameters

Used when a Consumer supplies a portletHandle
that is not scoped by the supplied
registrationHandle.

Security

InvalidRegistration

Used when a Consumer supplies aregistrationHandle/registrationState pairthat is not recognized by the Producer. This includes
when no registrationHandle is supplied, but aregistration is required.

Interface

InvalidCookie

Used only when the environment at the Producer has
timed out AND the Producer needs the Consumer to
invoke initCookie() again and resend data that may
have been stored in sessions related to a cookie.

Interface

InvalidHandle

Used when the Consumer supplies an invalid Handle.

Web Services for Remote Portlets Specification75Interface

InvalidSession

Used only when a Producer session has timed out AND
the Producer needs the Consumer to invoke resend datathat may have been cached in the session.

Interface

InvalidUserCategory

The specified userCategory is not supported.

Interface

MissingParameters

Used when required parameters are missing.

Interface

OperationFailed

Normal execution of the operation failed. Check thedetailed message for reasons why.

Interface

PortletStateChangeRequired

Used when a Portlet needs to modify its persistent state,
but has been prevented from doing so.

Interface

UnsupportedLocale

The Portlet does not support generating markup for therequested locale. Since the Portlet is not required togenerate markup in the requested locale, a Portlet
returning this fault message is indicating that it processes
locales in a stricter manner and has no markup for therequested locales. The Consumer can treat this as a
specialization of the OperationFailed fault message anddoes not have to retry getting the markup in otherlocales.

Interface

UnsupportedMimeType

The Portlet does not support generating markup for therequested mime type.

Interface

UnsupportedMode

The Portlet does not support generating markup for therequested mode.

Interface

UnsupportedWindowStateThe Portlet does not support generating markup for therequested window state.

14 WSDL Interface Definition
Normative copies of the WSDL that MUST be referenced by Producers implementing thisspecification can be found at:5

http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_types.xsd - The
type, message and fault definitions for this specification. These definitions form the“urn:oasis:names:tc:wsrp:v1:types“ namespace.
http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_interfaces.wsdl The portType definitions for this specification. These definitions form the“urn:oasis:names:tc:wsrp:v1:intf“ namespace.

10

http://www.oasis-open.org/committees/wsrp/specifications/version1/wsrp_v1_bindings.wsdl The standard binding definitions for this specification. These definitions form the“urn:oasis:names:tc:wsrp:v1:bind“ namespace.

Web Services for Remote Portlets Specification

76

This WSDL defines the following portTypes:
1. WSRP_v1_Markup_PortType: All Producers MUST expose this portType.
2. WSRP_v1_ServiceDescription_PortType: All Producers MUST expose thisportType.
5

3. WSRP_v1_Registration_PortType: Only Producers supporting in-band registration ofConsumers need expose this portType.
4. WSRP_v1_PortletManagement_PortType: Producers supporting the Portlet
management interface expose this portType. If this portType is not exposed, thePortlets of the service are not configurable by Consumers.

10This WSDL defines the following SOAP bindings for these portTypes:
1. WSRP_v1_Markup_Binding_SOAP: All Producers MUST expose a port with thisbinding for the WSRP_v1_Markup_PortType (the Markup portType).
15

2. WSRP_v1_ServiceDescription_Binding_SOAP: All Producers MUST expose a portwith this binding for the WSRP_v1_ServiceDescription_PortType (theServiceDescription portType).
3. WSRP_v1_Registration_Binding_SOAP: Producers supporting the Registration
portType MUST expose a port with this binding for the
WSRP_v1_Registration_PortType.

2025

4. WSRP_v1_PortletManagement_Binding_SOAP: Producers supporting thePortletManagement portType MUST expose a port with this binding for the
WSRP_v1_PortletManagement_PortType.

15 References
15.1 Normative

30

35[Character Sets] http://www.iana.org/assignments/character-sets[Namespaces] http://www.w3.org/TR/REC-xml-names/[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels,
http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
[Schema] http://www.w3.org/TR/xmlschema-0/[SOAP] http://www.w3.org/TR/SOAP/[SSL/TLS] http://www.ietf.org/html.charters/tls-charter.html[URI/URL] http://www.ietf.org/rfc/rfc2396.txt[WSDL] http://www.w3.org/TR/wsdl

15.2 Non-Normative

40[Boyer-Moore] http://www.cs.utexas.edu/users/moore/best-ideas/string-searching/[DIME] http://www.ietf.org/internet-drafts/draft-nielsen-dime-02.txt[J2EE] http://java.sun.com/j2ee/[JSR168] http://www.jcp.org/jsr/detail/168.jsp[.Net] http://www.microsoft.com/net/[P3P] http://www.w3.org/TR/P3P/

Web Services for Remote Portlets Specification

77

5

10

15

[Requirements] http://www.oasis-open.org/committees/wsia/documents/Requirements200209-17.html[RLTC] http://www.oasis-open.org/committees/rights/[SAML] https://www.oasis-open.org/committees/security/[UDDI] http://www.uddi.org/specification.html[WS-Attachments] http://www-106.ibm.com/developerworks/webservices/library/wsattach.html[WS-I.org] http://www.ws-i.org/[WSIL] http://www-106.ibm.com/developerworks/webservices/library/ws-wsilspec.html[WSRP Whitepaper] Thomas Schaeck, Web Services for Remote Portals (WSRP)
Whitepaper,
http://www.oasis-open.org/committees/wsrp/documents/wsrp_wp_09_22_2002.pdf,
22 September, 2002.
[WS-Security] http://www.oasis-open.org/committees/wss/[XACML] https://www.oasis-open.org/committees/xacml/[XCBF] http://www.oasis-open.org/committees/xcbf/[XForms] http://www.w3.org/TR/xforms/[XML Digital Signatures] http://www.w3.org/Signature/[XML Encryption] http://www.w3.org/TR/xmlenc-core/

Web Services for Remote Portlets Specification

78

Appendix A: Glossary (Non-Normative)
ActionA term often used elsewhere for what this specification calls “Interaction”.

Attribute

A distinct characteristic of an object. An object’s attributes are said to describe theobject. Objects’ attributes are often specified in terms of their physical traits, suchas size, shape, weight, and color, etc., for real-world objects. Objects incyberspace might have attributes describing size, type of encoding, network
address, etc. Salient attributes of an object is decided by the beholder.

Authentication

To confirm a system entity’s asserted principal identity with a specified, or
understood, level of confidence.

ClientA system entity that accesses a web service.

ConsumerA system entity invoking Producers in a manner conforming to this specification.
For example a portal aggregating content from Portlets accessed using the
WSRP protocol.

End-User

A person who uses a device specific User-Agent to access a Web site.

Fragment

A piece of markup that is not part of a full document- part of aggregate- generally a markup language- can aggregate a set of fragments

Portal Page

Complete document rendered by a portal.

PortletProducer hosted component that generates content design for aggregating andprocesses interactions generated from that content.

Producer

A web service conforming to this specification.

SessionA finite duration interaction between system entities, often involving a user,
typified by the maintenance of some state of the interaction for the duration of theinteraction.

System Entity

An active element of a computer/network system. For example, an automatedprocess or set of processes, a subsystem, a person or group of persons thatincorporates a distinct set of functionality.

Time-OutA period of time after which some condition becomes true if some event has notoccurred. For example, a session that is terminated because its state has been
inactive for a specified period of time is said to “time out”.

Uniform
Resource
Locator (URL)

Defined as “a compact string representation for a resource available via theInternet.” URLs are a subset of URI.

User-Agent

A system entity that is used by an End-User to access a Web site. A user-agent
provides a run-time environment for distributed application components on theclient device.

Web Service

A Web Service is a software component that is described via WSDL and iscapable of being accessed via standard network protocols such as but not limited
to SOAP over HTTP.

Web SiteA hosted application that can be accessed by an End user using a user-agent

WSRP Service

Presentation oriented, interactive web services that can be aggregated byconsuming applications

Web Services for Remote Portlets Specification79

- WSRP services can be published, found, and bound in a standard manner,
describing themselves with standardized metadata
XML(Extensible
MarkupLanguage)

Extensible Markup Language, abbreviated XML, describes a class of data objects
called XML documents and partially describes the behavior of computer programs
which process them. XML is an application profile or restricted form of SGML, theStandard Generalized Markup Language [ISO 8879] See
http://www.w3.org/TR/REC-xml.

XML
Namespace

A name, identified by a URI reference, which are used in XML documents aselement types and attribute names. An XML namespace is often associated with
an XML schema. See http://www.w3.org/TR/REC-xml-names/.

Web Services for Remote Portlets Specification

80Appendix B: Common Values (Non-Normative)
There is significant value to defining values for various fields that Consumers and Producers
share without having to map to different values with the same semantic meaning. The following
sections define such common values.
5

B.1 Standard User Categories
To ease the mapping of End-Users to user categories and to facilitate plug-and-play, thefollowing standard category names are provided along with an abstract definition of semantics
associated with each. The specific semantics of these categories are left to each Portlet’s
implementation.

10

15

wsrp:full:

The content for this user category will typically encompass the fullfunctionality of the Portlet.

wsrp:standard:This user category is typically associated with End-Users who may
customize some set of properties for a Portlet.

wsrp:minimal:This user category is typically associated with End-Users who may viewa Portlet on a page but not modify any of its properties

Web Services for Remote Portlets Specification81

Appendix C: Data Structures List (Non-Normative)
The following lists the data structures this specification defines including the section numbers
for the defintions.
BlockingInteractionResponse (6.1.13)
5

RegistrationContext (5.1.21)

ClientData (6.1.7)

RegistrationState (5.1.20)

CookieProtocol (5.1.18)

RegistrationData (7.1.1)

DestroyFailed (8.1.1)

ResetProperty (5.1.13)
35

ResourceList (5.1.8)

Handle (5.1.2)

ResourceValue (5.1.6)

ID (5.1.4)

RuntimeContext (6.1.2)

InteractionParams (6.1.16)

ServiceDescription (5.1.19)
40

StateChange (6.1.14)

LocalizedString (5.1.5)

Templates (6.1.6)

MarkupContext (6.1.11)

UpdateResponse (6.1.12)

MarkupResponse (6.1.11)

UploadContext (6.1.15)
45

UserContext (6.1.18)

MarkupType (5.1.10)

UserProfile (6.1.17)

ModelDescription (5.1.17)- Contact Type (6.1.17.7)

ModelTypes (5.1.16)- EmployerInfo (6.1.17.2)

NamedString (6.1.8)- Online (6.1.17.5)

PortletContext (6.1.3)
25

SessionContext (6.1.1)

Key (5.1.3)

MarkupParams (6.1.9)
20

Resource (5.1.7)

Extension (5.1.1)

ItemDescription (5.1.9)
15

PropertyList (5.1.14)

CacheControl (6.1.5)

DestroyPortletsResponse (8.1.2)
1030

PortletDescription (5.1.11)

50- PersonName (6.1.17.1)- Postal (6.1.17.6)

PortletDescriptionResponse (8.1.3)- Telecom (6.1.17.4)

PortletPropertyDescriptionResponse (8.1.4)- TelephoneNum (6.1.17.3)

Property (5.1.12)

UserScopes (6.1.4)

PropertyDescription (5.1.15)
55

Web Services for Remote Portlets Specification82

Appendix D: Acknowledgments (Non-Normative)
D.1 WSIA committee members
The following individuals were members of the WSIA committee during the development of thisspecification (* indicates voting member when specification was finalized):
5 •Sasha Aickin*, Plumtree Software

30 •Eric van Lydegraf*, Kinzan•

Patel Ashish, France Telecom•

Michael Mahan, Nokia•

Stefan Beck, SAP•

Monica Martin*, Drake Certivo•

Dan Bongard, Kinzan•

Dale Moberg, Cyclone Commerce•

Kevin Brinkley, Intel•

Dean Moses, Epicentric

10 •Jeffery C. Broberg*, Novell

35 •Peter Quintas, Divine•

Rex Brooks*, Individual•

T.V. Raman, IBM Corporation•

Tyson Chihaya, Netegrity•

Shankar Ramaswamy, IBM Corporation•

Carlos Chue, Kinzan•

Eilon Reshef*, WebCollage•

Terry Cline, Peregrine Systems•

Graeme Riddell*, Bowstreet

15 •William Cox*, BEA Systems Inc

40 •Don Robertson, Documentum•

Suresh Damodaran, Sterling Commerce•

Royston Sellman, HP•

Alan Davies, SeeBeyond•

Sim Simeonov, Macromedia•

Jacques Durand, Fujitsu•

Davanum Srinivas, Computer Associates•

John Evdemon, Vitria•

Sandra Swearingen, DoD

20 •Sean Fitts, CrossWeave

45 •Gil Tayar*, WebCollage•

Greg Giles, Cisco•

Rich Thompson*, IBM Corporation•

Dan Gisolfi*, IBM Corporation•

Srinivas Vadhri*, Commerce One•

Timothy N. Jones, CrossWeave•

Vinod Viswanathan, Pointgain Corp.

•

Aditi Karandikar, France Telecom•

Charles Wiecha, IBM Corporation (chair)

25 •John Kelley, Individual

50 •Chad Williams, Epicentric•John Kneiling, Individual•

Kirk Wilson*, Computer Associates•

Ravi Konuru*, IBM Corporation•

Garland Wong, Kinzan•

Alan Kropp*, Vignette Corporation•

Bruce Lucas*, IBM Corporation

Web Services for Remote Portlets Specification

83D.2 WSRP committee members
The following individuals were members of the WSRP committee during the development of
this specification (* indicates voting member when specification was finalized):
•
5 •

•

Alejandro Abdelnur*, Sun Microsystems
Sasha Aickin*, Plumtree Software

Dan Machak*, TIBCO Software Inc.

40 •Monica Martin*, Drake Certivo•

Subbu Allamaraju*, BEA SYSTEMS INC•

Khurram Mahmood, Peoplesoft•

Olin Atkinson*, Novell•

Lothar Merk, IBM Corporation•

Amir Blich*, SAP•

Madoka Mitsuoka*, Fujitsu•

Chris Braun*, Novell•

Takao Mohri, Fujitsu

10 •Jeff Broberg, Novell

45 •Adam Nolan*, Reed Elsevier•

Rex Brooks*, Individual•Petr Palas*, Moravia IT•

Mark Cassidy, Netegrity•

Gregory Pavlik, HP•

Dave Clegg, Sybase•Peter J Quintas*, Divine•

Ugo Corda, SeeBeyond•

Raj Ramesh*, CommerceOne

15 •T.J. Cox*, Novell

50 •Sunit Randhawa*, Fujitsu•

William Cox*, BEA SYSTEMS INC•

Nigel Ratcliffe*, Factiva•

Michael C. Daconta, McDonald Bradley•

Eilon Reshef*, WebCollage•

Ron Daniel Jr., Interwoven•

Mark Rosenberg, TIBCO Software Inc.

•

Angel Luis Diaz, IBM Corporation•

Joe Rudnicki*, U.S. Department of the Navy

55 •Thomas Schaeck*, IBM Corporation (chair)

20 •Brian Dirking*, Stellent•

Jane Dynin, Plumtree Software•

Robert Serr, Divine•

Gino Filicetti*, Bowstreet•

Gennady Shumakher*, SAP•

Adrian Fletcher, BEA SYSTEMS INC•

Steven Smith*, Capitol College•

Michael Freedman*, Oracle Corporation•

Davanum Srinivas, Computer Associates

25 •Ross Fubuni*, Plumtree Software

60 •Joseph Stanko, Plumtree Software•

Tim Granshaw, SAP•

Andrew Sweet, Perficient•

Mike Hillerman, Peoplesoft•

David Taieb, IBM Corporation•

Scott Huddleston, Divine•

Yossi Tamari*, SAP•

Richard Jacob*, IBM Corporation•

Gil Tayar*, WebCollage

30 •Timothy N. Jones, CrossWeave

65 •Rich Thompson*, IBM Corporation•

Aditi Karandikar, France Telecom•

Srinivas Vadhri, CommerceOne•

Jon Klein*, Reed Elsevier•

Stephen A. White, SeeBeyond•

Andre Kramer*, Citrix Systems, Inc•

Charles Wiecha*, IBM Corporation•

Alan Kropp*, Vignette Corporation•

Michael Young*, Plumtree Software

35 •Andreas Kuehne, Individual•

Carsten Leue*, IBM Corporation•

Susan Levine, Peoplesoft•

Eric van Lydegraf*, Kinzan

Web Services for Remote Portlets Specification84

Web Services for Remote Portlets Specification

70

71

Version 0.95

4/24/2003

Appendix E: Revision History (Non-Normative)
Rev

Date

By Whom

What

0.1
0.1.1

6/03/2002
6/04/2002
6/05/2002
6/06/2002

Rich Thompson
Carsten Leue
Rich Thompson
Carsten Leue

0.1.2
0.2

6/06/2002
7/09/2002

Rich Thompson

Initial Draft
Worked in some additional WSRP requirements
Added exemplary section to overview
Added request data to getFragment andinvokeAction
Added cloneEntities() & descriptive text
Modified as per face-2-face discussions

0.21
0.22
0.23

7/10/2002
7/19/2002
7/25/2002

0.3

8/01/2002

0.31

8/08/2002

Rich Thompson
Alan Kropp
Chris Braun

0.32

8/10/2002

0.4

8/16/2002

0.5

8/30/2002

0.7

9/27/2002

0.8

10/22/2002

0.85

12/10/2002

0.90
0.91
0.92

01/17/2003
02/03/2003
03/10/2003

Rich Thompson
Carsten Leue
Chris BraunRich Thompson
Thomas Schaeck
Alan Kropp
Rich Thompson
Carsten Leue
Mark Cassidy
Rich Thompson
Carsten Leue
Alan Kropp
Charlie Wiecha
Rich Thompson
Carsten Leue
Alan Kropp
Rich Thompson
Alan Kropp
Rich Thompson
Rich Thompson
Rich Thompson

Alan Kropp,
Rich Thompson
Rich Thompson
Rich Thompson

Carsten Leue
Rich Thompson
Rich Thompson

Refactored data objects
Reflect discussion on email list
Added WSDL and included some explanations
Reformat style
Reflect discussion
Migrate to OASIS spec template
Reflect email list and concall discussions
Reflect discussion
Fill out more of spec template
Markup section
Environment initialization section
Incorporated misc. comments/discussion
Introduction section and explanation of sections
Updated Markup section
Rewrote Markup section, reflect discussion
WSRP Use cases
Cross references to requirements
Incorporated misc. comments/discussion
UDDI, Additional data structure factoring
Updated Security section
Reflect Sept. F2F discussion/decisions
Rewrite Intro
Propose caching support
Propose Properties support
Reflect decisions from weekly TC calls
Reflect decisions from Nov. F2F and TC calls
Reflect issue resolutions
Reflect TC decision through Jan ’03 F2FReflect Change Request resolutions

72

Appendix F: Notices

73
74
75
76
77
78
79
80
81

OASIS takes no position regarding the validity or scope of any intellectual property or otherrights that might be claimed to pertain to the implementation or use of the technology describedin this document or the extent to which any license under such rights might or might not be
available; neither does it represent that it has made any effort to identify any such rights.
Information on OASIS's procedures with respect to rights in OASIS specifications can be foundat the OASIS website. Copies of claims of rights made available for publication and any
assurances of licenses to be made available, or the result of an attempt made to obtain ageneral license or permission for the use of such proprietary rights by implementors or users of
this specification, can be obtained from the OASIS Executive Director.

82
83
84

OASIS invites any interested party to bring to its attention any copyrights, patents or patentapplications, or other proprietary rights which may cover technology that may be required to
implement this specification. Please address the information to the OASIS Executive Director.

85
86

Copyright © The Organization for the Advancement of Structured Information Standards[OASIS] 2001. All Rights Reserved.

87
88
89
90
91
92
93
94
95

This document and translations of it may be copied and furnished to others, and derivative
works that comment on or otherwe explain it or assist in its implementation may be prepared,
copied, published and distributed, in whole or in part, without restriction of any kind, provided
that the above copyright notice and this paragraph are included on all such copies andderivative works. However, this document itself does not be modified in any way, such as byremoving the copyright notice or references to OASIS, except as needed for the purpose ofdeveloping OASIS specifications, in which case the procedures for copyrights defined in the
OASIS Intellectual Property Rights document must be followed, or as required to translate it
into languages other than English.

96
97

The limited permissions granted above are perpetual and will not be revoked by OASIS or its
successors or assigns.

98
99
100
101
102

This document and the information contained herein is provided on an “AS IS” basis and
OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOTINFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

wsrp-specification-1.0