[Web Services for Remote Portlets Specification v2.0]
[Committee Draft], [8 September 2006]
Artifact Identifier:
wsrp-2.0-spec-cd-03-highlight
Location:
TC: http://www.oasis-open.org/committees/wsrp
Current: http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec.html
This Version: http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cd-03.html
Artifact Type:
Specification
Technical Committee:
OASIS Web Services for Remote Portlets TC
Chair:
Rich Thompson, IBM Corporation <richt2@us.ibm.com>
Editor:
Rich Thompson, IBM Corporation <richt2@us.ibm.com>
Contributors:
Subbu Allamaraju, BEA Systems
<subbu@bea.com>
Michael Freedman, Oracle Corporation
<Michael.Freedman@oracle.com>
Richard Jacob, IBM Corporation
<richard.jacob@de.ibm.com>
Andre Kramer, Citrix Systems
<andre.kramer@eu.citrix.com>
OASIS Conceptual Topic Model Area:
Abstract:
Integration of remote content and application logic into an End-User presentation has been a task requiring significant custom programming effort. Typically, vendors of aggregating applications, such as a portal, write special adapters for applications and content providers to accommodate the variety of different interfaces and protocols those providers use. The goal of this specification is to enable an application designer or administrator to pick from a rich choice of compliant remote content and application providers, and integrate them with just a few mouse clicks and no programming effort. This revision of the specification adds Consumer managed coordination, additional lifecycle management and a set of related aggregation enhancements.
This specification is the effort of the OASIS Web Services for Remote Portlets (WSRP) Technical Committee which aims to simplify the effort required of integrating applications to quickly exploit new web services as they become available.
This standard layers on top of the existing web services stack, utilizing existing web services standards and will leverage emerging web service standards (such as policy) as they become available. The interfaces defined by this specification use the Web Services Description Language (WSDL).
Status:
This document was last revised or approved by the WSRP TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.
Technical Committee members should send comments on this specification to the Technical Committee's email list. Others should send comments to the Technical Committee by using the "Send A Comment" button on the Technical Committee's web page at www.oasis-open.org/committees/wsrp.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (www.oasis-open.org/committees/wsrp/ipr.php).
The non-normative errata page for this specification is located at www.oasis-open.org/committees/wsrp.
Notices
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in 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 found at 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 a general 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.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, 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.
Copyright © OASIS Open 2001, 2002, 2003, 2004, 2005, 2006. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise 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 and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing 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.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
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 NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Short Table of Contents
Table of Contents
3.7 Types of Stateful Information
3.9 Producer Mediated Data Sharing
3.10 Consumer Mediated Coordination
3.11 Information Passing Mechanisms
4.1 Service Description Operations
4.4 Portlet Management Operations
5 Service Description Interface
5.1.12 PropertyDescription Type
5.1.15 ParameterDescription Type
5.1.16 PortletDescription Type
5.1.22 ExtensionDescription Type
5.1.24 ServiceDescription Type
5.1.27 RegistrationContext Type
5.2 getServiceDescription Operation
6.1.12 NavigationalContext Type
6.1.24 BlockingInteractionResponse Type
6.1.26 HandleEventsFailed Type
6.1.27 HandleEventsResponse Type
6.2.1 Caching of markup fragments
6.4.1 performBlockingInteraction Operation
6.4.3 Updating Enduring Portlet State
6.7 Consumer Transitions across Bindings
6.8 Stateful Portlet Scenarios
6.10.1 "wsrp:normal" Window State
6.10.2 "wsrp:minimized" Window State
6.10.3 "wsrp:maximized" Window State
6.10.4 "wsrp:solo" Window State
6.11.1 wsrp:eventHandlingFailed
6.11.2 wsrp:newNavigationalContextScope
6.12.1 User Category Assertions
7.3 modifyRegistration Operation
7.5 getRegistrationLifetime Operation
7.6 setRegistrationLifetime Operation
8 Portlet Management Interface
8.1.2 DestroyPortletsResponse Type
8.1.3 PortletDescriptionResponse Type
8.1.4 PortletPropertyDescriptionResponse Type
8.1.6 CopyPortletsResponse Type
8.1.8 ExportPortletsResponse Type
8.1.11 ImportPortletsFailed Type
8.1.12 ImportPortletsResponse Type
8.1.14 GetPortletsLifetimeResponse Type
8.1.15 SetPortletsLifetimeResponse Type
8.2 getPortletDescription Operation
8.5 getPortletsLifetime Operation
8.6 setPortletsLifetime Operation
8.11 setExportLifetime Operation
8.12 setPortletProperties Operation
8.13 getPortletProperties Operation
8.14 getPortletPropertyDescription Operation
9.1 Authentication of Consumer
9.2 Confidentiality & Message Integrity
10.2.3 Extended BNF Description of URL formats
10.2.4 Method=get in HTML forms
12.2 wsrp-extra:extendedURLParameters
Appendix A. Glossary (Non-Normative)
Appendix B. Common Values (Non-Normative)
Appendix C. Types of state (Non-Normative)
Appendix D. Coordination mechanisms (Non-Normative)
Appendix E. Data Structures List (Non-Normative)
Appendix F. Acknowledgments (Non-Normative)
F.1 WSRP Technical Committee members
The Web Services for Remote Portlets specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS Technical Committee. It is based on the requirements gathered and on the concrete proposals made to the committee.
Scenarios that motivate WSRP functionality include:
Many of the non-portal use cases were originally defined by the Web Services for Interactive Applications (WSIA) OASIS Technical Committee. The WSIA use cases [1] have become input to the ongoing effort in this area by the WSRP OASIS Technical Committee. For additional details and documents, refer to the committee information available at http://www.oasis-open.org/committees/wsrp/ and http://www.oasis-open.org/committees/wsia/.
This specification accounts for the fact that Producers (web services conforming to this specification) and Consumers (applications consuming Producers in a manner conforming to this 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. At the same time, attention has also been paid to ensure a reasonable mapping to technologies for producing markup fragments (e.g. webparts, JSR 168 portlets, etc).
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, such as WS-Policy [A102] in future versions.
Portals and other Web applications render and aggregate information from different sources and provide it in a compact and easily consumable form to End-Users.
Among typical sources of information are web services. Traditional data-oriented web services, however, require aggregating applications to provide specific presentation logic for each of these web services. Furthermore, each aggregating application communicates with each web service via its unique interface. This approach is not well suited to dynamic integration of business applications and content as a plug-and-play solution.
This specification solves this problem by introducing a set of presentation-oriented web service interfaces that allow the inclusion of and interaction with content from a web service. Such a presentation-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 incorporate content from these web services using code which is not specific to the content source.
This specification uses four roles (End-User, Consumer, Producer and Portlet) to help delineate responsibilities. Implementations are free to combine multiple roles provided all resulting responsibilities are met.
The protocol defined by this specification describes the conversation between Producers and Consumers on behalf of End-Users (clients of the Consumer). Producers are presentation-oriented web services that host Portlets which are able to render markup fragments and process user interaction requests. Consumers use these web services as part of presenting markup to End-Users and managing the End-User's interaction with the markup.
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 some specification of the Producer's environment and a particular configuration of any settings or properties the Portlet exposes.
Producers are modeled as containers of Portlets. The Producer provides a set of web service interfaces, including:
In order to allow different levels of sophistication for both the Producer and Consumer, parts of this functionality are optional. Various examples of how a Producer might implement particular functionality for varying levels of sophistication and with regards to implementing some of the optional portions of the protocol are contained throughout this document.
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 the Consumer and Producer which provides the scope for a set of interactions between them.
A particular Portlet is identified with a portletHandle. The Consumer uses portletHandles throughout the communication to address and interact with Portlets through the Producer's web service interfaces. 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, the details of which are discussed later. Such a uniquely 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 the Consumer registration.
A Consumer is an application that incorporates, in part or whole, an intermediary function that communicates with presentation-oriented web services (i.e. Producers and the Portlets they host) on behalf of its End-Users. It gathers and aggregates the markup delivered by the Portlets and other view components for presentation to the End-User. Because of this intermediary role, Consumers are often compared to "message switches" that route messages between various parties. One typical Consumer is a portal, which mediates the markup and the interaction with this markup between End-Users and presentation-oriented web services. Another typical Consumer is an e-Commerce application that aggregates manufacturer-provided content with its own content. 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. Additionally, the event distribution and public navigational state portions of this specification cause Consumers to also have the role of a coordination broker, providing inter-Portlet and End-User / Consumer to Portlet coordination.
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 the processing of user interface logic, such as the validation of End-User input, as far toward the user agent as possible. Client-side scripting and XForms[2] represent technologies that can be leveraged 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.
The main purpose of a Consumer acting as a content intermediary for various Producer/Portlets is the preparation and presentation of aggregated markup to an End-User. In addition, the Consumer needs to manage the processing of interactions with that markup in order to properly correlate the interactions with the (potentially stateful) environment that produced the markup.
While some of the following steps are optional, the typical flow of interactions between these actors is:
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].
Cross references to the [Requirements] developed by both the WSIA and WSRP technical committees are designated throughout this specification by a hyperlink to the requirement contained where the requirement number is enclosed in square brackets (e.g. [A100]).
Whenever this specification uses the prefix "wsrp:" in what appears to be a QName, it is referring to the URI urn:oasis:names:tc:wsrp:v2:types.
The normative definitions for all data structures defined by this specification are contained in the WSDL referenced in [Section 15]. For the convenience of the reader, the types are also declared in a non-normative manner just prior to the first use of the structure. These non-normative declarations use an IDL like syntax to describe the structures, where the leading [R] indicates a field is required and [O] indicates it is optional. These indicators are followed by an indication of the type for the field and then its name. If the type is one defined by this specification, then the type declaration also serves as a hyperlink to the definition of that type. All types not defined by this specification come from the XML Schema Datatype definitions in http://www.w3c.org/TR/xmlschema-2/. An example of a type being declared in this IDL like style is:
| NewTypeDefinition | |
| [R] WSRPDefinedType | someRequiredField |
| [O] xsdDefinedType | someOptionalField |
The major design goals for the protocol defined by this specification are simplicity, extensibility and efficiency. This specification seeks to accomplish these goals whenever possible by leveraging other standards. 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.
This specification seeks to leverage both existing and emerging web service standards whenever possible. The following are particularly noted as relevant standardization efforts:
CC/PP - Defines syntax for describing a device's capabilities and user preferences.
Character Sets - Character set encoding
JSR168 - Java Community Process effort defining the Java Portlet Specification.
P3P - Defines how a Producer/Portlet may publish its privacy policy so that a Consumer could enforce End-User privacy preferences.
Namespaces - Defines how XML Namespaces are declared and used.
SAML - Defines how authentication and authorization information may be exchanged.
Schema - Defines how types are defined and associated with each other.
SOAP - Defines how to invoke web service interfaces.
SSL/TLS - Defines secure transport mechanisms.
URL - Defines URI (includes URL) syntax and encoding. We note that this is being superceded by the definition of an IRI (see http://www.ietf.org/rfc/rfc3987.txt), but are waiting for greater support in the marketplace before changing the descriptions to be IRI oriented. Those using IRIs locally will need to properly encode their IRIs into URIs during this transition period.
WSDL - Defines how abstract interfaces and their concrete realizations are defined.
WS-I.org - Has defined a base profile for use of the WSDL, SOAP and UDDI web services standards such that interoperability is maximized.
WS-Security - Defines how document level security standards apply to SOAP messages.
XACML - Defines syntax for expressing authorization rules.
XCBF - Defines how to exchange biometric data.
XML Digital Signatures - Defines how portions of an XML document are digitally signed.
XML Encryption - Defines how to encrypt/decrypt portions of an XML document.
XOP/MTOM - Defines how to move binary elements of an XML InfoSet into and out of separate parts of a multipart mime message such that the XML InfoSet may be transported efficiently.
JSR286 - Java Community Process effort defining v2 of the Java Portlet Specification.
WS-I.org - Defining additional profiles (e.g. Security) for use of web service standards such that interoperability is maximized.
WS-Notification - Defining how to discover, subscribe to and receive notifications using web services.
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 text of 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 15]. 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 messages must be exchanged in order 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.
Since there are multiple ways to secure a message exchange between the Consumer and Producer (there are transport means such as SSL/TLS and message level means such as WS-Security) this specification uses the term "secure communication" to mean that at least one of these means will be used to secure messages. Note that this specification does not include mechanisms to reach agreement about which means to use as other efforts are addressing that issue in a manner that applies to all web services.
It is often necessary to pass data to operations. Typed data objects are defined as the transport mechanism wherever possible. The schema definitions of these structures includes the <any namespace="##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 defined[3] "type" attribute to reference the correct schema on each such extension element, and use of either the Producer's WSDL (default), or the WSRP defined "wsrp-extra" (urn:oasis:names:tc:wsrp:extra:v1) namespace 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.
"Lifecycle" is a term used to describe how items become available, are interacted with, and finally are destroyed. The two lifecycles included in this specification are:
Enduring: This lifecycle starts with an explicit operation to create the item and ends either via a lifetime expiring (when resource leasing is in use) or via an explicit operation to destroy the item. Examples include the registrationHandle and context of a Consumer Configured Portlets.
Transient: This lifecycle can either start with an explicit operation OR as a side effect of some other operation [A204]. The item created is transient and no explicit operation is required to destroy it. This specification generally includes an expires element when a transient item is created so that anything resources at the Consumer related to the item may be reclaimed at an appropriate time. An example of items using this lifecycle is session creation.
Scope is a term used to describe when something is valid. An item often scopes both the usage 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 and ends 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 an enduring lifecycle. This scope is referenced throughout the protocol using a registrationHandle. The registrationHandle is created and destroyed using either the in band mechanism, i.e. by declaring support for the Registration portType, or by an out of band mechanism, whereby the registrationHandle is created and destroyed by means outside this specification [R354]. If a Producer supports the leasing feature, then this scope can also be ended in a scheduled manner.
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, if one exists. This scope ends for Consumer Configured Portlets when the reference to the Portlet is explicitly released or, if the Producer supports the leasing feature, released in a scheduled manner. As such it encompasses all interactions with the Portlet. This scope has an enduring 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 the Producer Offered Portlets.
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 the session holding that state is released (either via an explicit operation on the Producer or via a timeout mechanism). As such it encompasses a set of operation invocations in which the Consumer has supplied the session's identifier. This scope has a transient lifecycle and is established by the Producer returning a new sessionID. The Consumer MUST respect this new session scope as described in [Section 6.1.1].
WSRP defines a number of resources are items for which a reference is supplied on relevant operations (examples include a portlet, which is referenced via a portletHandle). WSRP resources that which can use a the leasing concept (scheduled destruction of the item WSRP resource with opportunity for extending the scheduled termination time) . All such items of this specification go through three stages of availability; namely:
Because the WSRP protocol operates over connectionless technologies, the Producer must be able to return information to the Consumer, with the understanding that this information will be sent 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 that both page refresh and bookmarked pages will generate what the End-User expects. To supply the bookmarking and page refresh capabilities End-Users expect, the Consumer MAY store this type of 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:
Enduring state: This is state that has an enduring lifecycle, that is, exists until either the Consumer or Producer explicitly discards it, potentially as part of the expiration of a lease. This specification defines two kinds of enduring state with each referred to via a handle that MUST remain invariant once the Producer supplies it to the Consumer:
While each of these types of state can have portions which are opaque to the Consumer, each can also have portions which are described to the Consumer such that programmatic impacts, such as state-based coordination, can be effected by the Consumer.
This specification does not mandate that either the Producer or the Consumer is stateful [A201]. In the getMarkup, handleEvents and performBlockingInteraction calls, the navigationalContext 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 and bookmarking by the End-User. In order to support the URL length restrictions of some browsers, the Consumer may need to cache the navigational type of state and just supply a reference to it on the URL. 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.
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/caching mechanisms [A202].
The nature of the conversation between the client and the Consumer, for purposes of this section, 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].
Producers may implement data sharing mechanisms 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.20] specifies how the Consumer is to process Producer's grouping, which are defined by the groupID parameters.
Shared data areas introduce implementation challenges in clustered environments. In such an environment, 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 shared data even in such situations.
Consumers may implement mechanisms through which Portlets, and any other view components the Consumer aggregates, react in a coordinated manner. Each of these mechanisms enables event-driven Consumer applications. This specification defines two such 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 a particular Producer service is outside the scope of this specification.
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 the Consumer aggregates from the same Producer [A503]. Common causes of such shared state include use of a common backend system (e.g. database) and Producer-mediated data sharing. In addition, the Consumer can selectively distribute events, including ones it generates itself, among the Portlets. For these reasons, there is a "three-step" capability built into the protocol. Note that this is an extension of the WSRP v1 two-step protocol as the additional step, event distribution, is entirely optional. This enables Consumers to provide coordinated cross-portlet response to the End-User's interaction while providing the equivalent user experience as WSRP v1 for those Consumers not supporting event distribution [C409].
The three non-overlapping steps of the protocol are:
Examples of when one of the optional steps (performBlockingInteraction and handleEvents) might not be used include:
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 and distributing events among the Portlets using handleEvents, regardless of whether those interactions have side effects on other Portlets at the Producer, is well-defined independent of the order of getMarkup invocations on the Portlets.
Since the transport layer is often used to store various pieces of information (e.g. J2EE load balancing 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 in conformance with the rules established by RFC2109[4]. 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 and unexpected behavior for the End-User. We also note that failure to properly do this management will eliminate the ability to use Producers that set requiresInitCookie to a value other than "none".
Load balancing is a part of the Producer environment that cannot easily be managed from within the protocol. Load balancing is highly dependent on mechanisms in the transport, for example the use of cookies in HTTP. In order to permit load balancing to function, regardless of 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 ensure that cookies are properly supplied in subsequent requests for the End-User.
This specification defines four interfaces whose operations have the following signatures:
The Service Description interface, a required interface, defines an operation for acquiring the Producer's metadata.
| ServiceDescription = getServiceDescription (registrationContext, desiredLocales, portletHandles, userContext ); |
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 in this interface avoids the problems associated with moving cookies between bindings.
| MarkupResponse = getMarkup (registrationContext, portletContext, runtimeContext, userContext, markupParams); |
| MarkupResponse ResourceResponse = getResource (registrationContext, portletContext, runtimeContext, userContext, markupParams, resourceParams ); |
| BlockingInteractionResponse = performBlockingInteraction (registrationContext, portletContext, runtimeContext, userContext, markupParams, interactionParams); |
| HandleEventsResponse = handleEvents (registrationContext, portletContext, runtimeContext, userContext, markupParams, eventParams); |
| ReturnAny = initCookie (registrationContext, userContext); |
| ReturnAny = releaseSessions (registrationContext, sessionIDs[], userContext); |
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, lifetime, userContext); |
| RegistrationState = modifyRegistration (registrationContext, registrationData, userContext); |
| ReturnAny = deregister (registrationContext, userContext); |
| Lifetime = getRegistrationLifetime (registrationContext, userContext); |
| Lifetime = setRegistrationLifetime (registrationContext, userContext, lifetime); |
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, lifetime); |
| DestroyPortletsResponse = destroyPortlets (registrationContext, portletHandles[], userContext); |
| GetPortletsLifetimeResponse = getPortletsLifetime (registrationContext, portletContext[], userContext); |
| SetPortletsLifetimeResponse = setPortletsLifetime (registrationContext, portletContext[], userContext, lifetime); |
| CopyPortletsResponse = copyPortlets (toRegistrationContext, toUserContext, fromRegistrationContext, fromUserContext, fromPortletContexts[], lifetime); |
| ExportPortletsResponse = exportPortlets (registrationContext, portletContext[], userContext, lifetime, exportByValueRequired); |
| ImportPortletsResponse = importPortlets (registrationContext, importContext, importPortlet[], userContext, lifetime); |
| ReturnAny = releaseExport (exportContext, userContext); |
| Lifetime = setExportLifetime (registrationContext, exportContext, userContext, lifetime); |
| PortletContext = setPortletProperties (registrationContext, portletContext, userContext, propertyList); |
| PropertyList = getPortletProperties (registrationContext, portletContext, userContext, names); |
| PortletPropertiesDescriptionResponse = getPortletPropertyDescription (registrationContext, portletContext, userContext, desiredLocales); |
A Producer may be discovered through mechanisms such as [UDDI] or [ebXML Registry], 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 to register or use the Producer.
The following data structures are needed by this interface:
The Extension structure contains the payload extension mechanism for vendor and application extensions. These arbitrary elements are required to be from namespaces other than the WSRP "types" namespace (urn:oasis:names:tc:wsrp:v2:types) and extend their containing data structure. They are designed to communicate extended information between the Consumer and Producer. Consumers and Producers SHOULD NOT rely on receiving back any extensions passed to or returned from an invocation. Each such extension element carries a single child element which MUST declare its type using the schema-defined "type" attribute [5]. It is RECOMMENDED extensions be of type xsd:string (where xsd stands for http://www.w3c.org/2001/XMLSchema) , or be of a type from the WSRP-defined "wsrp-extra" namespace (urn:oasis:names:tc:wsrp:extra:v1) or be of a type defined in the Producer's WSDL as this enables Consumers to prepare an appropriate serializer/deserializer. We expect many extensions will be of the type QNamedString or QNamedStringArray (from the "wsrp-extra" namespace) and encourage their use in this manner. The other option is for each message to connect the extension to a type declared in a schema using the "schemaLocation" attribute as used by schema. Consumers and Producers are not required to process information supplied using these extension elements.
| Extension | |
| [O] Object | any |
Members:
Handles are opaque references that are passed between the Consumer and Producer.
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:
The maximum length of a handle is restricted to 255 characters. It is strongly RECOMMENDED these characters be chosen from the first 127 characters of the Unicode character set so that it is feasible to represent the value in no more than 255 bytes of storage. 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 restricts string (maximum length = 255) |
Keys 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 is restricted to 255 characters. We STRONGLY RECOMMEND these characters be chosen from the first 127 characters of the Unicode character set so that it is feasible to represent the value in no more than 255 bytes of storage. Not following this recommendation will likely cause information to be lost as the value is stored and retrieved.
| Key restricts string (maximum length = 255) |
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 be chosen from the first 127 characters of the Unicode character set so that it is feasible to represent the value in no more than 4096 bytes of storage. Not following this recommendation will likely cause information to be lost as the value is stored 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 of these (e.g. a sessionID is per user per Portlet and therefore a Consumer is likely to store a very large number of them).
| ID restricts string (maximum length = 4096) |
The LocalizedString structure describes both the value for a particular locale and the resource 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 |
Members:
This structure provides the value of a resource for a locale.
| ResourceValue | |
| [R] string | xmlLang |
| [R] string | value |
| [O] Extension | extensions[] |
Members:
The Resource structure carries the values for a resource in a set of locales.
| Resource | |
| [R] string | resourceName |
| [R] ResourceValue | values[] |
| [O] Extension | extensions |
Members:
This is an array of Resource structure, each of which carries the values for a localized resource in various locales.
| ResourceList | |
| [R] Resource | resources[] |
| [O] Extension | extensions[] |
Members:
This structure is used to describe custom items a Consumer is allowed to use when interacting with the Portlets at the Producer.
| ItemDescription | |
| [R] string | itemName |
| [R] LocalizedString | description |
| [O] Extension | extensions[] |
Members:
The MarkupType data structure is used to carry Portlet metadata that is mimeType specific.
| MarkupType | |
| [R] string | mimeType |
| [R] string | modes[] |
| [R] string | windowStates[] |
| [O] string | locales[] |
| [O] Extension | extensions |
Members:
The EventDescription structure provides the information needed to describe a Portlet's events.
| EventDescription | |
| [R] QName | name |
| [O] QName | aliases[] |
| [O] QName | type |
| [O] anyURI | schemaLocation |
| [O] ModelTypes | schemaType |
| [O] LocalizedString | description |
| [O] LocalizedString | hint |
| [O] LocalizedString | label |
| [O] Extension | extensions |
Members:
Since an event's name can be referred to in a wildcard fashion (see [Section 5.1.16]), Portlet developers are encouraged to organize their event's local names in a hierarchical manner and MUST use the '.' character to delimit levels within the hierarchy. An example of such an organization would be events carrying changed address information on an application being organized as "applicant.address.streetChanged", "applicant.address.cityChanged", etc. Such an organization would allow another Portlet's metadata to simply say that it is interested in all events with names in the "applicant.address" branch of the hierarchy by specifying an interest in "applicant.address.". The trailing '.' tells the Consumer that this is not the end of the hierarchy and the the Portlet is interested in all events with names in this branch of the hierarchy.
Each property of a Portlet is described using the following structure.
| PropertyDescription | |
| [R] QName | name |
| [R] QName | type |
| [O] anyURI | schemaLocation |
| [O] LocalizedString | description |
| [O] LocalizedString | label |
| [O] LocalizedString | hint |
| [O] string | usage[] |
| [O] QName | aliases[] |
| [O] Extension | extensions |
Members:
The ModelTypes structure contains the payload mechanism for declaring the types referenced by the description types.
| ModelTypes | |
| [R] Object | any[] |
Members:
The set of properties of a Portlet are described in its metadata using the following structure.
| ModelDescription | |
| [O] PropertyDescription | propertyDescriptions[] |
| [O] ModelTypes | modelTypes |
| [O] Extension | extensions |
Members:
Portlet parameters are modeled as an array of strings, such that type information does not need to be declared, and are described using the following structure.
| ParameterDescription | |
| [R] string | identifier |
| [O] QName | names[] |
| [O] LocalizedString | description |
| [O] LocalizedString | label |
| [O] LocalizedString | hint |
| [O] Extension | extensions |
Members:
The 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] MarkupType | markupTypes[] |
| [O] ID | groupID |
| [O] LocalizedString | description |
| [O] LocalizedString | shortTitle |
| [O] LocalizedString | title |
| [O] LocalizedString | displayName |
| [O] LocalizedString | keywords[] |
| [O] ID | portletID |
| [O] QName | publishedEvents[] |
| [O] QName | handledEvents[] |
| [O] ParameterDescription | navigationalParameterDescriptions[] |
| [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] boolean | mayReturnPortletState |
| [O] Extension | extensions |
Members:
The Property data structure is used to carry typed information between the Consumer and the Producer. Each property includes a name and type (carried using the xsi:type attribute) [A505] [A507]. The primary reason for including type information is situations when the receiving party does not have a relevant PropertyDescription.
| Property | |
| [R] QName | name |
| [O] QName | type |
| [O] string | xmlLang |
| [O] Object | value[] |
Members:
The ResetProperty data structure carries the name of a Property for which the Consumer wants the value reset to the default.
| ResetProperty | |
| [R] QName | name |
Members:
A PropertyList gathers a set of Property structures together for transmitting between the Consumer and Producer.
| PropertyList | |
| [O] Property | properties[] |
| [O] ResetProperty | resetProperties[] |
| [O] Extension | extensions[] |
Members:
It is an error for a property to be referenced by both the properties and resetProperties arrays. The Producer MUST return an InvalidParameters fault message if the Consumer supplies a property in both the properties array and the resetProperties array of a PropertyList.
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:
The ExtensionPart structure contains a set of fields for describing one part of a protocol extension.
| ExtensionPart | |
| [R] QName | name |
| [R] QName | type |
| [O] anyURI | schemaLocation |
| [O] ModelTypes | schemaType |
| [O] string | extendedTypes[] |
| [O] Extension | extensions[] |
Members:
The ExtensionDescription structure contains a set of fields for describing a protocol extension.
| ExtensionDescription | |
| [R] QName | name |
| [R] ExtensionPart | parts[] |
| [O] QName | aliases[] |
| [O] LocalizedString | description |
| [O] LocalizedString | label |
| [O] LocalizedString | hint |
| [O] Extension | extensions[] |
Members:
The ExportDescription structure contains a set of fields for describing export capabilities and restrictions.
| ExportDescription | |
| [O] integer | recommendedExportSize |
| [O] Extension | extensions[] |
Members:
The ServiceDescription structure contains a set of fields that describe the offered services of the Producer.
| ServiceDescription | |
| [R] boolean | requiresRegistration |
| [O] PortletDescription | offeredPortlets[] |
| [O] ItemDescription | userCategoryDescriptions[] |
| [O] ExtensionDescription | extensionDescriptions[] |
| [O] ItemDescription | customWindowStateDescriptions[] |
| [O] ItemDescription | customModeDescriptions[] |
| [O] CookieProtocol | requiresInitCookie |
| [O] ModelDescription | registrationPropertyDescription |
| [O] string | locales[] |
| [O] ResourceList | resourceList |
| [O] EventDescription | eventDescriptions[] |
| [O] string | supportedOptions[] |
| [O] ExportDescription | exportDescription |
| [O] boolean | mayReturnRegistrationState |
| [O] Extension | extensions[] |
Members:
The Lifetime structure provides information regarding when a particular itemWSRP resource is scheduled to be expunged. This introduces the ability of Producers and Consumers to cleanup related artifacts in scenarios such as the other party no longer being available.
| Lifetime | |
| [R] dateTime | currentTime |
| [R] dateTime | terminationTime |
| [O] duration | refreshDuration |
| [O] Extension | extensions[] |
Members:
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 return enduring state at registration scope to the Consumer and indicate any change in the scheduled destruction of the registration.
| [O] base64Binary | registrationState |
| [O] Lifetime | scheduledDestruction |
| [O] Extension | extensions[] |
Members:
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 | registrationHandle |
| [O] base64Binary | registrationState |
| [O] Lifetime | scheduledDestruction |
| [O] Extension | extensions[] |
Members:
This 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 is requesting 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.
This operation allows a Producer to provide information about its capabilities in a context-sensitive manner (e.g. registration may be required to discover the full capabilities of a Producer) [R303].
| ServiceDescription = getServiceDescription (registrationContext, desiredLocales, portletHandles, userContext ); | |
| Faults: | InvalidRegistration, ModifyRegistrationRequired, OperationFailed, ResourceSuspended |
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 whenever additional data is required, the registrationPropertyDescription field) with the Producer [R300] [R301] [R303]. Note that the RegistrationContext parameter is not likely to be supplied when an unregistered Consumer invokes getServiceDescription. This allows the Consumer to gain access to the information required to successfully register. It is recommended that Consumers invoke getServiceDescription after registering in order to receive 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.
When generating the ServiceDescription response the Producer SHOULD use the desiredLocales (an array of strings) to control what locales are returned for localized strings.
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.
The optional portletHandles parameter provides a means for a Consumer to restrict the set of Portlets for which it is requesting getServiceDescription return information. When the Consumer does not supply this parameter, the Producer MUST return a portletDescription for each of the "Producer Offered Portlets" the Consumer has access to through the supplied registrationContext If the Consumer supplies portletHandles that do not refer to "Producer Offered Portlets", the Producer is free to ignore those portletHandles.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
As interactive presentation-oriented web services, all 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 both the signatures for these operations and how the concepts of mode and window state impact the generation of the markup.
The following additional data structures are needed by this interface:
The SessionContext structure contains the ID and expires information the Consumer needs to refer to the session in subsequent invocations.
| SessionContext | |
| [O] ID | sessionID |
| [O] int | expires |
| [O] Extension | extensions[] |
Members:
If the Producer returns an InvalidSession fault message after returning a sessionID, the Consumer MUST NOT resupply that sessionID on a subsequent invocation and SHOULD reinvoke the operation that caused the fault message without any sessionID and supply any data that may have been stored in the session.
The SessionParams structure contains the session information the Consumer is supplying to the Portlet for connection to a Portlet session.
| SessionParams | |
| [O] ID | sessionID |
| [O] Extension | extensions[] |
Members:
The RuntimeContext structure defines a collection of fields used only in transient interactions between the Producer and Consumer.
| RuntimeContext | |
| [R] string | userAuthentication |
| [R] Key | portletInstanceKey |
| [R] string | namespacePrefix |
| [O] Templates | templates |
| [O] SessionParams | sessionParams |
| [O] Extension | extensions[] |
Members:
The PortletContext structure is used as a parameter on many operations to supply the Portlet information that was returned to the Consumer.
| PortletContext | |
| [R] Handle | portletHandle |
| [O] base64Binary | portletState |
| [O] Lifetime | scheduledDestruction |
| [O] Extension | extensions[] |
Members:
This 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 specification or custom values the Consumer has indicated it supports. If another value is specified and the Consumer does not understand it, the Consumer should ignore the cache control and treat the content as non-cacheable. The following values are defined by this specification:
The CacheControl structure contains a set of fields needed for the Portlet to manage cached markup 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 | expires |
| [R] string | userScope |
| [O] string | validateTag |
| [O] Extension | extensions[] |
Members:
The 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 | defaultTemplate |
| [O] string | blockingActionTemplate |
| [O] string | renderTemplate |
| [O] string | resourceTemplate |
| [O] string | secureDefaultTemplate |
| [O] string | secureBlockingActionTemplate |
| [O] string | secureRenderTemplate |
| [O] string | secureResourceTemplate |
| [O] Extension | extensions[] |
Members:
The CCPPProfileDiff structure holds the information defined by the CC/PP standard for declaring differences from the referenced profiles.
| CCPPProfileDiff | |
| [R] string | diffName |
| [R] string | description |
| [O] Extension | extensions[] |
Members:
The CCPPHeaders structure holds the information defined by the CC/PP standard.
| CCPPHeaders | |
| [R] string | profile |
| [O] CCPPProfileDiff | profileDiffs[] |
| [O] Extension | extensions[] |
Members:
The ClientData structure contains information the client supplied to Consumer about itself, including user-agent identification and capabilities.
| ClientData | |
| [O] string | userAgent |
| [O] CCPPHeaders | ccppHeaders |
| [O] string | requestVerb |
| [O] Extension | extensions[] |
Members:
The NamedString type provides a standardized way of carrying a simple name/value pair.
| NamedString | |
| [R] string | name |
| [O] string | value |
Members:
The NavigationalContext type provides a means to carry both the opaque and public portions of the Portlet's navigational state. Comments regarding this type of state from [Section 3.7], [Section 3.8] and [Section 6.8] apply equally to all components of this structure.
| NavigationalContext | |
| [O] string | opaqueValue |
| [O] NamedString | publicValues[] |
| [O] Extension | extensions[] |
Members:
Both the Producer and Consumer supply values to each other for the opaqueValue and publicValues fields. The Consumer needs to return the current value for the opaqueValue field, but can apply updates to the publicValues field as part of state-based coordination between Portlets and other Consumer constituents. These statements are true for all operations receiving or returning the NavigationalContext structure [C401]. While Consumer policy will govern when values from sources other than the Portlet update the publicValues, Consumers MUST apply Portlet supplied values (i.e. supplied on a portlet url parameter or on a response from performBlockingInteraction or handleEvents) to the publicValues and SHOULD supply the same value to Portlets which provide a navigationalParameterDescription referencing the same QName in the names array. An example of when this might not be appropriate is when the Portlets are related to the same Producer offered portlet handle. The context in which the Consumer is using Portlets related to the same Producer offered portlet handle will determine whether or not such Portlets will share the same publicValues. For example, a Consumer may choose to share a publicValue related to the End User's name between such Portlets and not share a publicValue related to a stock symbol.
The MimeRequest structure contains information frequently used to control generation of items with varying mime types.
| MimeRequest | |
| [R] boolean | secureClientCommuncation |
| [R] string | locales[] |
| [R] string | mimeTypes[] |
| [R] string | mode |
| [R] string | windowState |
| [O] ClientData | clientData |
| [O] NavigationalContext | navigationalContext |
| [O] string | markupCharacterSets[] |
| [O] string | validateTag |
| [O] string | validNewModes[] |
| [O] string | validNewWindowStates[] |
| [O] Extension | extensions[] |
Members:
class="insert">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 this specification.
The schema definition of the MarkupParams structure extends the common MimeRequest definition (see [Sections 6.1.13]) without any additional fields and provides the data 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 the interaction 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.
The schema definition of the ResourceParams structure extends the common MimeRequest definition (see [Sections 6.1.13]) adding fields specific to invoking the getResource operatione.
| ResourceParams (also see the fields defined in [Sections 6.1.13]) | |
| [R] ID | resourceID |
| [O] string | resourceState |
| [O] NamedString | formParameters[] |
| [O] UploadContext | uploadContexts[] |
Members:
The MimeResponse structure contains common fields relative to returning an item described by a mime type.
| MimeResponse | |
| [O] boolean | useCachedItem |
| [O] string | mimeType |
| [O] string | itemString |
| [O] base64Binary | itemBinary |
| [O] string | locale |
| [O] boolean | requiresRewriting |
| [O] CacheControl | cacheControl |
| [O] string | ccppProfileWarning |
| [O] Extension | extensions[] |
Members:
The schema definition of the ResourceContext structure extends the common MimeResponse definition (see [Sections 6.1.16]) without any additional fields.
The ResourceResponse structure contains fields for returning various items in response to a getResource invocation.
| ResourceResponse | |
| [R] ResourceContext | resourceContext |
| [O] SessionContext | sessionContext |
| [O] Extension | extensions[] |
Members:
The schema definition of the MarkupContext structure extends the common MimeResponse definition (see [Sections 6.1.16]), adding fields relative to returning a Portlet's markup.
| MarkupContext (also see the fields defined in [Sections 6.1.16]) | |
| [O] string | preferredTitle |
Members:
The MarkupResponse structure contains fields for returning various items in response to a getMarkup invocation.
| MarkupResponse | |
| [R] MarkupContext | markupContext |
| [O] SessionContext | sessionContext |
| [O] Extension | extensions[] |
Members:
The EventPayload structure provides a wrapper for the data carried by an event.
| EventPayload | |
| [R] Object | any |
Members:
The Event structure provides the references back to the QName and payload datatype provided by the EventDescription.
| Event | |
| [R] QName | name |
| [O] QName | type |
| [O] EventPayload | payload |
| [O] Extension | extensions[] |
Members:
The UpdateResponse structure contains the items normally returned by performBlockingInteraction.
| UpdateResponse | |
| [O] SessionContext | sessionContext |
| [O] PortletContext | portletContext |
| [O] MarkupContext | markupContext |
| [O] Event | events[] |
| [O] NavigationalContext | navigationalContext |
| [O] string | newWindowState |
| [O] string | newMode |
Members:
For optimization purposes this structure allows markup to be returned even while state changes, events and mode/windowState change requests are also returned. The semantics of this are that the markup reflects the current Portlet state and assumes any requested changes to the mode and/or windowState are honored by the Consumer.
The BlockingInteractionResponse structure contains the various items performBlockingInteraction can return.
| BlockingInteractionResponse | |
| [O] UpdateResponse | updateResponse |
| [O] string | redirectURL |
| [O] Extension | extensions[] |
Members:
The following is an enumerated set of QNames (the wsrp: prefix refers to the URI "urn:oasis:names:tc:wsrp:v2:types") defined as ErrorCodes by this specification for use in HandleEventsFailed, FailedPortlets and ImportPortletsFailed types. These ErrorCodes have the following meanings:
Additional reasons may be constructed by Producers, though automatic recovery becomes less likely with such additional definitions. As a result, the reason fields are defined as LocalizedString so that they are reasonable to display to administrative users.
The HandleEventsFailed structure contains the 0-based index of an event in the incoming events array that could not be processed fully by the Producer, and the reason for failure.
| HandleEventsFailed | |
| [R] int | index[] |
| [R] ErrorCodes | errorCode |
| [O] LocalizedString | reason |
| [O] Extension | extensions[] |
Members:
The HandleEventsResponse structure contains the various items handleEvents can return.
| HandleEventsResponse | |
| [O] UpdateResponse | updateResponse |
| [O] HandleEventsFailed | failedEvents[] |
| [O] Extension | extensions[] |
Members:
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.4.3].
The UploadContext structure contains fields specific to uploading data to the Portlet.
| UploadContext | |
| [R] string | mimeType |
| [R] base64Binary | uploadData |
| [O] NamedString | mimeAttributes[] |
| [O] Extension | extensions[] |
Members:
The InteractionParams structure contains fields specific to invoking the performBlockingInteraction operation.
| InteractionParams | |
| [R] StateChange | portletStateChange |
| [O] string | interactionState |
| [O] NamedString | formParameters[] |
| [O] UploadContext | uploadContexts[] |
| [O] Extension | extensions[] |
Members:
The EventParams structure contains fields specific to invoking the handleEvents operation.
| EventParams | |
| [R] StateChange | portletStateChange |
| [R] Event | events[] |
| [O] Extension | extensions[] |
Members:
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 from this 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 QNamedString (from the "wsrp-extra" namespace) and encourage its use in this manner.
| UserProfile | |
| [O] PersonName | name |
| [O] dateTime | bdate |
| [O] string | gender |
| [O] EmployerInfo | employerInfo |
| [O] Contact | homeInfo |
| [O] Contact | businessInfo |
| [O] Extension | extensions[] |
Members:
The PersonName structure carries the detailed fields for the parts of an End-User's name.
| PersonName | |
| [O] string | prefix |
| [O] string | given |
| [O] string | family |
| [O] string | middle |
| [O] string | suffix |
| [O] string | nickname |
| [O] Extension | extensions[] |
Members:
The EmployerInfo structure contains the detailed fields concerning the End-User's employer.
| Employerinfo | |
| [O] string | employer |
| [O] string | department |
| [O] string | jobtitle |
| [O] Extension | extensions[] |
Members:
The TelephoneNum structure is used to describe the subfields of a phone number.
| TelephoneNum | |
| [O] string | intcode |
| [O] string | loccode |
| [O] string | number |
| [O] string | ext |
| [O] string | comment |
| [O] Extension | extensions[] |
Members:
The 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[] |
Members:
The Online structure is used to describe various types of web-oriented contact information.
| Online | |
| [O] string | |
| [O] string | uri |
| [O] Extension | extensions[] |
Members:
The Postal structure carries the detailed fields describing a particular address.
| Postal | |
| [O] string | name |
| [O] string | street |
| [O] string | city |
| [O] string | stateprov |
| [O] string | postalcode |
| [O] string | country |
| [O] string | organization |
| [O] Extension | extensions[] |
Members:
The Contact structure is used to describe a location for the End-User.
| Contact | |
| [O] Postal | postal |
| [O] Telecom | telecom |
| [O] Online | online |
| [O] Extension | extensions[] |
Members:
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 for communicating this information are being defined elsewhere (e.g. WS-Security defines how to carry User Information in a SOAP header). There are several use cases for the application-level information carried in this structure, particularly in the absence of authenticated security-level information, namely; logging of remote invocations, interoperable assertions of unauthenticated information, personalization of the user experience, etc.
| UserContext | |
| [R] Key | userContextKey |
| [O] string | userCategories[] |
| [O] UserProfile | profile |
| [O] Extension | extensions[] |
Members:
The Consumer requests the markup for rendering the current state of a Portlet by invoking:
| MarkupResponse = getMarkup (registrationContext, portletContext, runtimeContext, userContext, markupParams); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidCookie, InvalidHandle, InvalidRegistration, InvalidSession, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, ResourceSuspended, UnsupportedLocale, UnsupportedMimeType, UnsupportedMode, UnsupportedWindowState |
This operation's semantics are that the Consumer is aggregating a page which includes the Portlet's markup.
For performance reasons the Consumer might prefer to cache markup across a series of requests. The Producer passes information about the cacheability of the markup fragment in the cacheControl structure returned in a MarkupContext structure. The Consumer can infer from this information when it may cache markup and when the cached markup needs to be invalidated and updated by a new call to getMarkup.
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 field is empty, the Portlet has provided no guidance and the Consumer MAY apply whatever cache policy it chooses. For a Portlet to indicate the markup is not cacheable, it will need to return a cacheControl structure with a value of zero in the expires field.
The expires field of the cacheControl structure provides a time duration during which it is valid 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 the validateTag 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.
Consumers should be aware that invoking performBlockingInteraction and/or handleEvents may cause cached markup 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 will address this issue.
The Consumer requests a resource by invoking:
| MarkupResponse ResourceResponse = getResource (registrationContext, portletContext, runtimeContext, userContext, markupParams, resourceParams ); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidCookie, InvalidHandle, InvalidRegistration, InvalidSession, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, ResourceSuspended, UnsupportedLocale, UnsupportedMimeType, UnsupportedMode, UnsupportedWindowState |
This operation's semantics are that the client/client-agent has requested additional information in a manner that utilized the Consumer as a proxy for supplying that information. As the Consumer is only being used as a proxy for accessing the resource, a number of techniques for storing the Portlet's navigationalContext" are not available to it. As a result, while the Portlet's navigationalContext" is supplied to this operation, neither the URL nor the response are permitted to change this navigationalContext". If a logical side effect of the invocation is changing the Portlet's navigationalContext", either the Portlet or the Producer will need to manage this change until the next opportunity to return the navigationalContext" to the Consumer.
This operation can be is used to fetch a resource whenever the activated URL has specified a value for the wsrp-resourceID portlet URL parameter and is the preferred mechanism whenever a value of true is specified for the wsrp-preferOperation (see [Section 10.2.1.1.3.3]. It provides all the contextual information needed for a Portlet to re-establish its state relevant to the End-User so that the generated response is able to take that state into account. This operation reuses the MarkupResponse structure since any mime type could be returned. Consumers SHOULD supply a value of "*" in the mimeTypes field of the MarkupParams structure as the returned object is likely to just be streamed to the End-User.
Resources which are inserted into the Consmer's aggregated page MUST follow the guidelines in [Section 10.4] for the mime types described there and the relevant fragment rules, if any, for other mime types.
For performance reasons the Consumer might prefer to cache resources across a series of requests. The Producer passes information about the cacheability of the resource representation in the cacheControl structure returned in a MarkupContext structure. The Consumer can infer from this information when it may cache the resource and when the cached resource needs to be invalidated and updated by a new call to getResource. All of the cache semantics described in [Section 6.2.1] applies to the caching of resources as well.
End-User interactions with the generated markup may result in invocations for the Portlet to respond to the interactions [A400]. In the case where the invocations may change 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.
This operation requires that both the Consumer beginning the generation of the aggregated page (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: | AccessDenied, InconsistentParameters, InvalidCookie, InvalidHandle, InvalidRegistration, InvalidSession, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, PortletStateChangeRequired, ResourceSuspended, UnsupportedLocale, UnsupportedMimeType, UnsupportedMode, UnsupportedWindowState |
The Consumer has to wait for the response from performBlockingInteraction before invoking getMarkup on the Portlets it is aggregating. This permits any Producer-mediated sharing 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 the aggregated page. Consumers doing this will enable End-User bookmarking of the aggregated page for later use. In order to support such bookmarking and reduce issues related to potentially 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 repeated invocations as the End-User may activate the link that caused the invocation more than once.
Note, 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 navigationalContext that will be returned from the operation and not the navigationalContext that was passed to it. Also, the markup should be generated presuming that any requested mode or windowState changes are honored. This ensures consistency when the optimization is not used and the Consumer invokes getMarkup after performBlockingInteraction returns.
A useful way of describing the distinction between an interaction and an event is that an interaction is an encodable event (i.e. can be referenced by presentation markup) with an opaque payload which the Consumer will always attempt to deliver to the Portlet that generated the markup. This differences result in the need for a different signature that the Consumer uses to distribute events to a Portlet; namely:
| HandleEventsResponse = handleEvents (registrationContext, portletContext, runtimeContext, userContext, markupParams, eventParams); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidCookie, InvalidHandle, InvalidRegistration, InvalidSession, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, PortletStateChangeRequired, ResourceSuspended, UnsupportedLocale, UnsupportedMimeType, UnsupportedMode, UnsupportedWindowState |
The events (carried within eventParams) provide a means by which a Portlet can be notified about changes in the Consumer application incorporating the Portlet's markup. These notifications could have originated from another Portlet or directly from the Consumer. It is the Consumer which determines which events to distribute to which Portlets, usually based on the needs of the Consumer application and the metadata concerning the events Portlets can publish and/or handle. Since events are independent notifications and the Consumer manages event distribution, Portlets should not expect a particular event distribution behavior (either on event ordering or whether a particular event is distributed to any of the Portlets that can process it).
In order for the inherent overhead of remote invocations to not degrade End-User performance to unacceptable levels, WSRP collapses invocations that are equivalent outside of the event being processed into a single invocation that deals with an array of events.
Since events are independent notifications, both the Consumer and Producer/Portlet are encouraged to deal with events in a simple time-ordered manner. The protocol defines no semantic meaning to the order of the events nor to the invocation of handleEvents that carried a particular set of events to the Portlet.
As many technologies used to implement Portlets do not protect against concurrent updates to runtime state, Producers hosting such Portlets will need to consider each, potentially concurrent, handleEvents invocation as transferring a portion of the overall queue of events for the Portlet to process. The Producer could also need to manage the serialization of the event processing with connections back to the response messages at appropriate times.
The processing of an event can potentially impact any portion of a Portlet's state (namely; portletState, session state and navigational state). Relevant to the enduring portletState, we would particularly note that cloning may occur and that the handling of the portletStateChange flag, which provides the Consumer control over cloning, is detailed in [Section 6.4.3].
Events can return requests to the Consumer to change the mode or windowState of the Portlet. The Consumer SHOULD honor a handleEvents invocation returning requests to change mode or windowState provided they do not conflict with other such requests. Since the policy for handling conflicting requests is up to the Consumer implementation, Portlet developers SHOULD be aware that the impact on the overall layout MAY cause the Consumer to not honor a request to change windowState.
In designing how a Portlet and Consumer interact in order to update the enduring state of the Portlet, the following items were considered:
This combination requires that all enduring Portlet state changes happen in a manner that has Consumer approval for the change to occur, while the Portlet decides both when the change is required and its exact character. The Consumer indicates whether or not it is safe for the Portlet to modify its enduring state by setting the portletStateChange field in the InteractionParams or EventParams structures. If the Consumer has set the portletStateChange flag to "readWrite", the Portlet MAY modify its enduring state regardless of whether it is persisted on the Producer or Consumer. Only if the Portlet's enduring state is modified and it is persisted on the Consumer should a PortletContext be returned to the Consumer and such a PortletContext MUST reference the portletHandle which was supplied by the Consumer.
If the Consumer has set the portletStateChange field to "cloneBeforeWrite", enduring state changes are allowed only if the Producer first clones the Portlet. If the Producer does not clone the Portlet, processing attempts to modify enduring state MUST proceed as if the Consumer had specified "readOnly" for portletStateChange. If the Producer clones the Portlet, processing attempts to modify enduring state on the new Portlet SHOULD proceed as if the Consumer had specified "readWrite" for portletStateChange. The Producer returns the impact of any cloning to the Consumer, regardless of whether the portletState is persisted on the Producer or Consumer. 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 to any cloned Portlet as well.
If the Consumer has set the portletStateChange flag to "readOnly", the Portlet MUST NOT modify its enduring 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 enduring state. Commonly Consumer's will only set the portletStateChange flag to "readOnly" for End-Users that are not authorized to clone or customize the Portlet (e.g. an End-User using a guest account).
If the Producer implements access control that prevents Portlets from updating enduring state and a Portlet is unable to process the interaction without such an update, then the fault "PortletStateChangeRequired" MAY be thrown indicating the interaction processing failed.
This set of possibilities is depicted in the following figure:
In general, the Producer completely manages its own environment, including items such as the initialization of cookies when using the HTTP transport. There are cases, however, when 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 userContext); | |
| Faults: | AccessDenied, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
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.20]. If at any time the Producer throws a fault message ("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 to be thrown and include any data that may have been stored in a session related to a cookie.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
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 itemresources related to the sessionIDs):
| ReturnAny = releaseSessions (registrationContext, sessionIDs[], userContext); | |
| Faults: | AccessDenied, InvalidRegistration, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
After invoking releaseSessions the Consumer MUST NOT include any of the supplied sessionIDs on subsequent invocations.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
Consumers need to be careful about the support supplied by the web stack with regards to multiple 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 manner that 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 manner prescribed in RFC2109[16]. Consumers MUST respect the security setting on each cookie.
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.
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 a single 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.
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 the markup some other Portlet will generate.
The following table outlines the values for certain key parameters that support this scenario.
Method |
Parameter/Field |
Value |
Comments |
performBlockingInteraction |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session. |
|
InteractionParams / interactionState |
Consumer extracts value from link. |
Interaction state encoded on the URLs in the markup only. |
|
MarkupParams / navigationalContext |
Consumer extracts values from link. |
Navigational state encoded on the URLs in the markup only. |
|
InteractionResponse / navigationalContext |
This type of Portlet does not return navigational state. |
|
handleEvents |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session state. |
|
MarkupParams / navigationalContext |
Consumer supplies current value for the Portlet. |
Navigational state encoded on the URLs in the markup only. |
|
HandleEvents Response / navigationalContext |
This type of Portlet does not return navigational state. |
|
getMarkup |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session state. |
|
MarkupParams / navigationalContext |
Consumer extracts value from link. |
Navigational state from the URL. |
This type of Portlet does not maintain state at the Producer, but does return navigational state 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 their navigational state (i.e. the navigationalContext field) back to the Consumer. It is then the responsibility of the Consumer to retransmit the navigational state to the Producer with each request [A206].
A stateless Consumer can store the navigational state for all of its aggregated Portlets by returning 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 navigational state 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 has collected markup from all Portlets aggregated on the page, a getMarkup invocation is not allowed to modify the navigational state. Only invocations of performBlockingInteraction and handleEvents are allowed to modify the navigational state of a Portlet.
The following table outlines the values for certain key parameters that support this scenario.
Method |
Parameter/Field |
Value |
Comments |
performBlockingInteraction |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session state. |
|
InteractionParams / interactionState |
Consumer extracts value from link. |
Interaction state encoded on the URLs in the markup only. |
|
MarkupParams / navigationalContext |
Consumer extracts values from link or previous value. |
|
|
InteractionResponse / navigationalContext |
Portlet may compute a changed navigational state. |
|
handleEvents |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session state. |
|
MarkupParams / navigationalContext |
Consumer extracts values from link or previous value. |
|
|
HandleEventsResponse / navigationalContext |
Portlet may compute a changed navigational state. |
|
getMarkup |
RuntimeContext / sessionParams |
Producer provided session state |
No value as this Portlet uses no session state. |
|
MarkupParams / navigationalContext |
From link or from performBlockingInteraction/handleEvents operations. |
|
Portlets storing state locally on the Producer establish a session and return an opaque reference (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 return navigational state to the Consumer 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-User is a Consumer implementation choice [A304].
The following table outlines the values for certain key parameters that support this scenario.
Method |
Parameter/Field |
Value |
Comments |
performBlockingInteraction |
RuntimeContext / sessionParams |
Producer provided session state |
With session state, the session handle offers ability to store information without increasing the message size to the Consumer. |
|
InteractionParams / interactionState |
Consumer extracts value from link. |
Interaction state encoded on the URLs in the markup only. |
|
MarkupParams / navigationalContext |
Consumer extracts values from link or previous value. |
|
|
InteractionResponse / navigationalContext |
Portlet may compute a changed navigational state. |
|
handleEvents |
RuntimeContext / sessionParams |
Producer provided session state |
With session state, the session handle offers ability to store information without increasing the message size to the Consumer. |
|
MarkupParams / navigationalContext |
Consumer extracts values from link or previous value. |
|
|
HandleEventsResponse / navigationalContext |
Portlet may compute a changed navigational state. |
|
getMarkup |
RuntimeContext / sessionParams |
Producer provided session state |
With session state, the session handle offers ability to store information without increasing the message size to the Consumer. |
|
MarkupParams / navigationalContext |
From link or from performBlockingInteraction/handleEvents operations. |
|
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 the Consumer 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 or a HandleEventsResponse. The Consumer MUST respect requests to change the mode outside of exceptional circumstances (e.g. access control restrictions), but the Portlet must not depend on such a request being respected.
During getMarkup, getResource, handleEvents and performBlockingInteraction invocations the Consumer indicates to the Portlet its current mode via the MarkupParams data structure.
Because modes are an extensible set of values, the following semantics apply relative to determining what modes are valid for the interactions of a Consumer with a Portlet:
The expected functionality for a Portlet in wsrp:view mode is to render markup reflecting the current state of the Portlet. The wsrp:view mode of a Portlet will include one or more screens that the End-User can navigate and interact with or it may consist of static content devoid of user 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.
Within the wsrp:edit mode, a Portlet should provide content and logic that let a user customize the behavior of the Portlet, though such customizations are not limited to markup generated while in this mode. 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 enduring state. How such changes impact Consumer management of Portlet usage by End-Users is discussed in [Section 6.4.3].
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.
In 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 the current configuration. This could be useful for a Consumer that offers an advanced layout capability.
The extensible RegistrationData structure provides a field for Consumers to declare additional custom modes. In addition, the extensible PortletDescription structure provides a field for Portlets to declare what modes they understand. The 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 defined by other parties, including future versions of this specification.
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. Portlets may request window state changes either through parameters on a link that an End-User activates or by returning a newWindowState from handleEvents or performBlockingInteraction. The Consumer SHOULD 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 on stateful settings after the Consumer has actually changed the window state.
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:
The wsrp:normal window state indicates the Portlet is likely sharing the aggregated page with other 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.
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 [A303] or hidden forms. The getMarkup operation can be invoked for the wsrp:minimized state just as for all other window states.
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 other Portlets in the aggregated page. A Portlet SHOULD generate richer content when its window state is wsrp:maximized.
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.
The extensible RegistrationData structure provides a field for Consumers to declare additional custom window states. In addition, the extensible PortletDescription structure contains a field for Portlets to declare what window states they understand. 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 name clashes with any values that may be defined by other parties, including future versions of this specification.
This specification defines the following events in the interest of promoting interoperability on a set of commonly encountered scenarios. All of these are defined within the WSRP types namespace (i.e. urn:oasis:names:tc:wsrp:v2:types).
This is a Consumer generated event which signals to the Portlet that the Consumer detected that errors occurred while distributing events. As a simple notification, this event carries no predefined payload, but does use an open content definition.
This is a Consumer generated event which notifies the Producer/Portlet that Consumer policy has determined that the scope of the navigationalContext has changed. While the value of the navigationalContext can change within any one such scope. the changing of scope will reset both the value and managing of the navigationalContext. The purpose for this notification is enabling those Producers/Portlets which choose an implementation style precluding the Consumer from fully managing the Portlet's navigationalContext to manage an extension to this state in a manner consistent with the Consumer's management for other Producers/Portlets (i.e. write an initial key into the Portlet's navigationalContext for later use in determining the correct extended state). While Consumer policy governs when this notification is sent, that policy MUST include providing those Portlets whose PortletDescription indicate they handle the wsrp:newNavigationalContextScope event an opportunity to write such a key into their navigationalContext on at least the initial pass through the three protocol steps for the current set of End-User interactions with the Consumer's pages which incorporate the Portlet (i.e. if the performBlockingInteraction operation is not invoked, the wsrp:newNavigationalContextScope event MUST be sent to the Portlet prior to the first invocation of the getMarkup operation for each End-User's set of interactions with Consumer pages). This guarantees the Producer/Portlet at least has an opportunity to write a key into the navigationalContext prior to the initial invocation of getMarkup for an End-User. Portlets indicating they handle this event SHOULD be aware this might limit the set of Consumers willing to incorporate them on the Consumer's pages. As a simple notification, this event carries no payload, but does use an open content definition.
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.16]. The Consumer may assert any of these 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.
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:
A Producer that supports in-band registration of Consumers exposes the optional registration interface. Regardless of whether or not the registration portType is exposed, Producers can offer out-of-band processes to register a Consumer [R354]. 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.25]).
The following additional data structures are needed by this interface:
The RegistrationData structure provides the means for the Consumer to supply the data required for registration with a Producer as well as protocol extensions that it supports [R355] [R356].
| RegistrationData | |
| [R] string | consumerName |
| [R] string | consumerAgent |
| [R] boolean | methodGetSupported |
| [O] string | consumerModes[] |
| [O] string | consumerWindowStates[] |
| [O] string | consumerUserScopes[] |
| [O] ExtensionDescription | extensionDescriptions[] |
| [O] Property | registrationProperties[] |
| [O] Extension | extensions[] |
Members:
Registration describes how a Consumer establishes a relationship with a Producer that will be referenced via an opaque handle in subsequent invocations the Consumer makes of the Producer [R350] [R352]. 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 [R400], unless the registration is using a scheduled destruction, so that the Producer may release related itemresources. When the Producer chooses to invalidate the registration identifier, it MUST inform the Consumer of this through a fault message on the next invocation specifying this registrationHandle so that the Consumer may release related itemresources.
| RegistrationContext = register (registrationData, lifetime, userContext); | |
| Faults: | MissingParameters, OperationFailed, |
If a Lifetime parameter is supplied, the Consumer is requesting the registration resource to be "leased" (i.e. use scheduled destruction) with the supplied value providing what the Consumer would otherwise provide on a subsequent setRegistrationLifetime invocation. If a Lifetime parameter is not supplied, the Consumer is indicating a preference for the registration resource to not use scheduled destruction. The returned RegistrationContext is used in all subsequent invocations to reference this registration [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 with potentially different settings (e.g. billing settings) resulting in multiple registrationHandles [R351].
The primary purpose the nillable userContext is provided to this operation is Producer logging.
This operation provides means for the Consumer to modify a relationship with a Producer [R353].
| RegistrationState = modifyRegistration (registrationContext, registrationData, userContext); | |
| Faults: | InvalidRegistration, MissingParameters, OperationFailed, OperationNotSupported, ResourceSuspended |
The supplied parameters reference a pre-existing registration and the modifications desired. If the Producer chooses to have the Consumer provide enduring storage, the entire resulting registration state is carried in the registrationState field of the returned RegistrationState structure.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
The Consumer MUST NOT consider a relationship with a Producer ended until either a successful invocation of deregister , elapsing of the scheduled destruction time or receipt of an InvalidRegistration fault message from the Producer on an invocation supplying the registrationHandle.
| ReturnAny = deregister (registrationContext, userContext); | |
| Faults: | InvalidRegistration, OperationFailed, OperationNotSupported |
After this operation is invoked, all handles created within the context of the RegistrationContext become invalid [R500] [R501] [R503]. It is a Producer implementation choice whether this immediately aborts in-progress operations or waits until all transient itemresources 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 InvalidRegistration fault message from the Producer on an invocation supplying the handle. The Producer MUST return a 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.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
This operation allows a Consumer to refresh its understanding of the scheduled destruction for a registration.
| Lifetime = getRegistrationLifetime (registrationContext, userContext); | |
| Faults: | AccessDenied, InvalidHandle, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended, |
If the nillable response from getRegistrationLifetime is nil, then scheduled destruction is not in use for this registration and the Consumer MUST use the deregister operation to destroy the registration.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
This operation allows a Consumer to request a change to the scheduled destruction of a registration. The Producer returns the actual change that was made.
| Lifetime = setRegistrationLifetime (registrationContext, userContext, lifetime); | |
| Faults: | AccessDenied, InvalidHandle, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended, |
If the nillable Lifetime parameter is nil, then this is a request to not use scheduled destruction as Consumer will use the deregister operation to destroy the registration. A nil response indicates that the Producer is not using scheduled destruction for this registration.
Producers MUST expose one or more logically distinct ways of generating markup and handling interactions 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 pre-configured 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 Portlet-generated 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 is called a "Consumer Configured Portlet".
Any Producer that supports cloning Portlets on performBlockingInteraction or handleEvents invocations MUST support the destroyPortlets operation.
The following additional data structures are needed by this interface:
The FailedPortlets structure contains a set of portletHandles which failed to be processed for the same reason and the reason for the failure.
| FailedPortlets | |
| [R] Handle | portletHandles[] |
| [R] ErrorCodes | errorCode |
| [O] LocalizedString | reason |
| [O] Extension | extensions[] |
Members:
The DestroyPortletsResponse structure carries an array of failed destroys.
| DestroyPortletsResponse | |
| [O] FailedPortlets | failedPortlets[] |
| [O] Extension | extensions[] |
Members:
The PortletDescriptionResponse structure contains the fields that getPortletDescription can return.
| PortletDescriptionResponse | |
| [R] PortletDescription | portletDescription |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The PortletPropertyDescriptionResponse structure contains the fields that getPortletPropertyDescription can return.
| PortletPropertyDescriptionResponse | |
| [O] ModelDescription | modelDescription |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The CopiedPortlet structure provides the Consumer with the details for a Portlet the copyPortlets operation has generated.
| CopiedPortlet | |
| [R] Handle | fromPortletHandle |
| [R] PortletContext | newPortletContext |
| [O] Extension | extensions[] |
Members:
The CopyPortletsResponse structure contains the fields that copyPortlets can return.
| CopyPortletsResponse | |
| [O] CopiedPortlet | copiedPortlets[] |
| [O] FailedPortlets | failedPortlets[] |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The ExportedPortlet structure represents a single exported Portlet.
| ExportedPortlet | |
| [R] Handle | portletHandle |
| [R] base64Binary | exportData |
| [O] Extension | extensions[] |
Members:
The ExportPortletsResponse structure contains the fields that exportPortlets can return. The exportPortlets operation can export many Portlets in a single invocation and this structure represents the bulk response.
| ExportPortletsResponse | |
| [O] base64Binary | exportContext |
| [O] ExportedPortlet | exportedPortlets[] |
| [O] FailedPortlets | failedPortlets[] |
| [O] Lifetime | lifetime |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The ImportPortlet structure represents a single exported Portlet representation which the Consumer wishes to import.
| ImportPortlet | |
| [R] ID | importID |
| [R] base64Binary | exportData |
| [O] Extension | extensions[] |
Members:
The ImportedPortlet structure represents a single response for the import of a Portlet representation.
| ImportedPortlet | |
| [R] ID | importID |
| [R] PortletContext | newPortletContext |
| [O] Extension | extensions[] |
Members:
The ImportPortletsFailed structure provides the Consumer with the details for a set of Portlets the importPortlets operation failed to process into reconstituted Portlets.
| ImportPortletsFailed | |
| [R] ID | importIDs[] |
| [R] ErrorCodes | errorCode |
| [R] LocalizedString | reason |
| [O] Extension | extensions[] |
Members:
The ImportPortletsResponse structure contains the fields that importPortlets can return. The importPortlets operation can import many Portlets in a single invocation and this structure represents the bulk response.
| ImportPortletsResponse | |
| [O] ImportedPortlet | importedPortlets[] |
| [O] ImportPortletsFailed | importFailed[] |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The PortletLifetime structure represents the lifetime for a single Portlet.
| PortletLifetime | |
| [R] PortletContext | portletContext |
| [R] Lifetime | scheduledDestruction |
| [O] Extension | extensions[] |
Members:
The GetPortletsLifetimeResponse structure contains the fields that getPortletsLifetime can return. The getPortletsLifetime operation can update many Portlets in a single invocation and this structure represents the bulk response.
| GetPortletsLifetimeResponse | |
| [O] PortletLifetime | portletLifetimes[] |
| [O] FailedPortlets | failedPortlets[] |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
The SetPortletsLifetimeResponse structure contains the fields that setPortletsLifetime can return. The setPortletsLifetime operation can update many Portlets in a single invocation and this structure represents the bulk response.
| SetPortletsLifetimeResponse | |
| [O] PortletLifetime | updatedPortlets[] |
| [O] FailedPortlets | failedPortlets[] |
| [O] ResourceList | resourceList |
| [O] Extension | extensions[] |
Members:
This operation allows a Producer to provide information about the Portlets it offers in a context-sensitive manner.
| PortletDescriptionResponse = getPortletDescription (registrationContext, portletContext, userContext, desiredLocales); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
Producers may choose to restrict access to the information returned in PortletDescriptionResponse based on the supplied registration and user contexts. 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 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 is denied when the Portlet reference is invalid).
When generating the PortletDescriptionResponse the Producer SHOULD use the desiredLocales to control what locales are supplied for localized strings.
This operation allows the Consumer to request the creation of a new Portlet from an existing Portlet.
| PortletContext = clonePortlet (registrationContext, portletContext, userContext, lifetime); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
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 to the 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 returns the Portlet's enduring state to the Consumer, the portletState 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.
If a Lifetime parameter is supplied, the Consumer is indicating a preference for the Portlet to be "leased" with the supplied value providing what the Consumer would otherwise provide on a subsequent setPortletsLifetime invocation. If a Lifetime parameter is not supplied, the Consumer is indicating a preference for the Portlet to not use scheduled destruction.
If a Producer chooses to return the enduring state of its Portlets to the Consumer, it is RECOMMENDED that the portletHandle encode the supplied registrationHandle. In this case, 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.
The returned PortletContext contains both the portletHandle and portletState fields for use 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 a registration and were not using scheduled destruction.
The Consumer MUST inform the Producer that a Consumer Configured Portlet which does not use leasing will no longer be used by invoking either the destroyPortlets or the deregister operation and MUST NOT consider such a Portlet to have been destroyed until one of these operations has been successfully invoked for that Portlet.
| DestroyPortletsResponse = destroyPortlets (registrationContext, portletHandles[], userContext); | |
| Faults: | InconsistentParameters, InvalidRegistration, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The supplied portletHandles is an array of type portletHandle, each of which the Consumer is informing the Producer it will no longer use. The Producer returns failures to destroy supplied portletHandles in the DestroyPortletsResponse structure. It is a choice of the Producer's implementation whether the itemresources related to the portletHandles are immediately reclaimed or whether transient itemresources are allowed to timeout first. A Consumer MUST NOT reference any of the supplied portletHandles after successfully invoking destroyPortlets and MAY reclaim itemresources related to the supplied portletHandles (e.g. portletState).
The primary purpose the nillable userContext is provided to this operation is Producer logging.
This operation allows a Consumer to refresh its understanding of the scheduled destruction for a set of Portlet.
| GetPortletsLifetimeResponse = getPortletsLifetime (registrationContext, portletContexts[], userContext); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
If the optional Lifetime field from getPortletsLifetime is not returned for a particular Portlet, then scheduled destruction is not in use for this Portlet and the Consumer MUST use the destroyPortlets operation to destroy the Portlet.
This operation allows a Consumer to request a change to the scheduled destruction of a set of Portlets. The Producer returns the actual changes that were made.
| SetPortletsLifetimeResponse = setPortletsLifetime (registrationContext, portletContext[], userContext, lifetime); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
If the nillable Lifetime parameter is nil, then this is a request to not use scheduled destruction as Consumer will use the destroyPortlets operation to destroy the Portlets. A nil response indicates that the Producer is not using scheduled destruction for this Portlet.
This operation provides the means for the Consumer to make new copies of a set of Portlets, potentially specifying a different registration scope for the new Portlets.
Since Consumers will commonly invoke this operation as part of a migration effort, this operation is a bulk operation. The Consumer supplies a list of Portlets it wants to copy. The Producer's response contains exactly one element for each entry in the supplied list.
| CopyPortletsResponse = copyPortlets (toRegistrationContext, toUserContext, fromRegistrationContext, fromUserContext, fromPortletContexts[], lifetime); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The supplied toRegistrationContext parameter provides the RegistrationContext that scopes the set of new Portlets being requested. If the toRegistrationContext parameter is not supplied, the new Portlets are to be scoped by the same RegistrationContext as the existing Portlets (i.e. the fromRegistrationContext). The supplied toUserContext provides information concerning the End-User requesting creation of the new Portlets in the toRegistrationContext. A null value means the Consumer is not indicating which End-User is making the request. The supplied fromRegistration parameter provides the RegistrationContext which scopes the set of Portlets supplied as the source for generating the new Portlets. The supplied fromUserContext provides information concerning the End-User requesting the new copy in the fromRegistrationContext. A null value means the Consumer is not indicating which End-User on whose behalf the request is being made. The fromPortletContexts parameter specifies the set of Portlets which are to serve as the basis for generating new Portlets. The returned CopyPortletsResponse contains information on both the set of new Portlets generated and a reason for each Portlet where the copy failed to generate a new Portlet.
If a Lifetime parameter is supplied, the Consumer is indicating a preference for the Portlets to be "leased" with the supplied value providing what the Consumer would otherwise provide on subsequent setPortletsLifetime invocations. If a Lifetime parameter is not supplied, the Consumer is indicating a preference for the Portlets to not use scheduled destruction.
The returned CopyPortletsResponse contains arrays for both the set of successfully copied Portlets and reasons for each Portlet where the attempt failed. When not returning a fault, the Producer MUST return exactly one entry in its response for each entry in the request to copyPortlets.
Consumers should be aware that processing invocations of copyPortlets may take significant time and should therefore break large bulk requests into chunks. However, even when the Consumer limits the request in this manner, the Producer is free to evaluate the cost of any given request and adjust the number of Portlets it copies in the response.
This operation allows the Consumer to get an opaque representation of a Portlet which can be supplied to the corresponding import operation to reconstitute the Portlet.
Since Consumers will commonly invoke this operation when taking a snapshot of all or a portion of itself (e.g. to package itself for deployment or migration), this operation is a bulk operation. The Consumer passes a list of Portlets for which it wants to obtain a representation. The Producer's response contains exactly one element for each entry in the supplied array of Portlets.
| ExportPortletsResponse = exportPortlets (registrationContext, portletContext[], userContext, lifetime, exportByValueRequired); | |
| Faults: | AccessDenied, ExportByValueNotSupported, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The supplied RegistrationContext sets the scope for the set of Portlets requested to be exported. The array of PortletContext elements specifies the set of Portlets where exported data is being requested. The UserContext parameter provides information about the End-User making the request. The exportByValueRequired parameter is a boolean indicating whether or not the usage intended by the Consumer requires that the export not contain references to data stored at the Producer. If the Consumer requires the Producer to export the Portlets by value and the Producer does not support such exports, the ExportByValueNotSupported fault MUST be returned.
If a Lifetime parameter is supplied, the Consumer is indicating a preference for any itemresources referenced by the export to be "leased" with the supplied value providing what the Consumer would otherwise provide on subsequent setExportLifetime invocations. If a Lifetime parameter is not supplied, the Consumer is indicating a preference for any itemresources referenced by the export to not use scheduled destruction. This parameter only applies when the Producer's export is not by value and is otherwise ignored.
The returned ExportPortletsResponse contains arrays for both the set of successfully exported Portlets and reasons for each Portlet where the export attempt failed. When not returning a fault, the Producer MUST return exactly one entry in its response for each entry in the request to exportPortlets.
Consumers should be aware that processing invocations of exportPortlets may take significant time and should therefore break large bulk requests into chunks. The Producer indicates its preferred request size in the recommendedExportSize field of its ServiceDescription. Consumers SHOULD limit their export requests to chunks no larger then this size. However, even when the Consumer limits the request to this size, the Producer is free to evaluate the cost of any given request and adjust the number of Portlets it exports in the response.
Note that the Producer is responsible for identifying the correct offered Portlet to clone from during an import. Producers should be aware that the importing Producer may be in a different place, time, and version from the exporting Producer. The mechanism for identifying the correct offered Portlet should be sufficiently tolerant to work in such situations. For the same reasons, the importing Producer should be capable of dealing with version differences between the representation of the Portlet in the exported data and the imported Portlet. Both of these imply a need to carry extra information in the exportData that allows the importing Producer to resolve such details.
The importPortlets operation reconstitutes a set of previously exported Portlets.
Since Consumers will commonly invoke this operation when reconstituting a particular configuration, this operation is a bulk operation. The Consumer passes a list of Portlets which it wants to be reconstituted. The Producer response MUST contain exactly one element for each entry in the list supplied to importPortlets.
| ImportPortletsResponse = importPortlets (registrationContext, importContext, importPortlet[], userContext, lifetime); | |
| Faults: | AccessDenied, ExportNoLongerValid, InconsistentParameters, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The importContext carries the data from the exportContext field associated with the Portlet representations by a response to a single invocation of the exportPortlets operation. The importPortlet array identifies the Portlets to be reconstituted. The userContext parameter provides information about the End-User making the request. The reconstituted Portlets or failure messages are returned in a corresponding array in the response. The relationship between the Portlet requested to be imported and the resulting reconstituted Portlet passed back in the response is maintained by a Consumer supplied identifier (importID).
If a Lifetime parameter is supplied, the Consumer is indicating a preference for the Portlets to be "leased" with the supplied value providing what the Consumer would otherwise provide on subsequent setPortletsLifetime invocations. If a Lifetime parameter is not supplied, the Consumer is indicating a preference for the Portlets to not use scheduled destruction.
The releaseExport operation provides the means for the Consumer to indicate to the Producer that it no longer needs to maintain any stored artifacts relative to a particular export.
| ReturnAny = releaseExport (exportContext, userContext); |
All that is needed to release an export is the exportContext from the original exportPortlets invocation. As defined, the releaseExport operation returns nothing to the Consumer and throws no fault. As a result, the Producer has full responsibility to recover from any failures associated with the attempt to release artifacts.
The primary purpose the nillable userContext is provided to this operation is Producer logging.
The setExportLifetime operation provides the means for the Consumer to request that the Lifetime of a particular export be changed.
| Lifetime = setExportLifetime (registrationContext, exportContext, userContext, lifetime); | |
| Faults: | AccessDenied, InvalidHandle, InvalidRegistration, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
This operation is only valid when the Producer has indicated that it has stored artifacts relative to an export by having returned a Lifetime structure. The Consumer indicates the particular export it is requesting the lifetime change for using the exportContext parameter and the desired new lifetime using the lifetime parameter.
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 declared in the metadata specific to a Portlet. This operation enables the Consumer to interact with this published portion of a Portlet's state.
| PortletContext = setPortletProperties (registrationContext, portletContext, userContext, propertyList); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
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 portletStateChange set to "readWrite" for a performBlockingInteraction invocation). The supplied set of property changes 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 of properties. 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 a property's value could impact the value of any of the Portlet's properties.
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 to display these for administrative purposes.
| PropertyList = getPortletProperties (registrationContext, portletContext, userContext, names); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The supplied names parameter is an array of strings each of which declares a property for which 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.
This operation allows the Consumer to discover the published properties of a Portlet and information (e.g. type and description) that could be useful in generating a user interface for editing the Portlet's configuration.
| PortletPropertiesDescriptionResponse = getPortletPropertyDescription (registrationContext, portletContext, userContext, desiredLocales); | |
| Faults: | AccessDenied, InconsistentParameters, InvalidHandle, InvalidRegistration, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, OperationNotSupported, ResourceSuspended |
The modelDescription returned in the PortletPropertyDescriptionResponse structure is a typed Property view onto the portion of the Portlet's enduring state that the user (referenced through the userContext) is allowed to modify. While it is possible the set of properties can change with time (e.g. the Portlet dynamically creates or destroys properties), Producers and Portlets SHOULD make the returned modelDescription as complete as possible.
When generating the PortletPropertyDescriptionResponse the Producer SHOULD use the desiredLocales to control which locales are supplied for localized strings.
Systems compliant with this specification will be exposed to the same security issues as other web service systems [A613]. For a representative summary of security concerns, refer to the Security and Privacy Considerations document produced by the XML-Based Security Services Oasis TC . One area to particularly note is that security information, including fields within the WSRP protocol that relate to a need for secure communication, is only as trustworthy as the means used to transmit the information.
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. In particular, the Technical Committee is producing a [Security Tech Note] which will call out the security concerns of the WSRP use case and provide pointers at relevant security-oriented work. The standards in the security area generally fall into two main categories: document-level mechanisms and transport-level mechanisms.
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 web services security roadmap becomes more fully specified by standards, and support for those standards becomes widely available from infrastructure components, that these will play an increasingly important role in the use of this specification [R414]. At the writing of this specification, there does not exist a standard for expressing policy issues, though several have been proposed. Consumers and Producers will need to work out how to exchange policy information outside of this protocol.
Use of transport-level security standards (e.g. SSL/TLS) to address the security issues involved in Consumers invoking Producers on behalf of End-Users 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 [R413].
Producer authentication of a Consumer may be achieved at the transport level through the use of 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 a business relationship between the Producer and Consumer [R402].
The WS-Security standard also specifies the means by which tokens, including those asserting the identity of the Consumer, may be included in a SOAP message. A number of profiles for suppling tokens that can be used for this purpose have already been defined. Since additional profiles continue to be defined, implementors are encouraged to consult the WS-Security TC's web site for the latest information [R402].
The WS-Security standard also specifies the means by which security features can be used to ensure SOAP message confidentiality and integrity. When employing message level security, implementors are encouraged to leverage these means in order to achieve message confidentiality or integrity, as needed [A604].
SSL/TLS may be used to ensure the contents of messages are neither tampered with nor decipherable by an unauthorized third party [A604]. Consideration needs to be given to both the communication between Producer and Consumer and communication between the End-User client and the Consumer.
For Producer - Consumer communication, the Producer declares the use of SSL/TLS in the service's WSDL by declaring an HTTPS service endpoint.
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.
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 [A605].
It should be noted that the security concept of access control is generally controlled by subsystems/protocols operating at a lower layer than the WSRP implementation/protocol and that this should not be confused with the application level concept of user categories, even when applications use the user categories to determine whether or not to show particular portions of the overall user interface.
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].
The Consumer indicates to the Portlet the preferred character encoding, using the markupCharacterSets 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 character set. If it is unable to generate markup in any of these character sets, the Portlet MUST return a fault message to the Consumer. When the SOAP binding is in use, the nature of XML requires that the markup use the same character set as the XML response message.
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.
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:
This implies that portlet URLs must be encoded so that the Consumer intercepts them and re-routes them to the correct Portlet at the Producer [A305], including the proper context. Because the same 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 is that 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:
As there is no clear advantage to either technique, both styles of portlet URL encoding are supported (see [Section 10.2.1] and [Section 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 that the following semantics be followed:
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.
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 encoding[18] 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 of the path of an URL, these values it MUST be strictly encoded (i.e. "&", "=", "/", and "?" need to be url-escaped) so that special URL characters do not invalidate the processing of the enclosing 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, the Consumer SHOULD leave the current value unchanged.
All portlet URLs (i.e. those the Consumer needs to rewrite) are demarcated in the markup by a token (wsrp_rewrite) both at the start (with a "?" appended to clearly delimit the start of the name/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 the information 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 |
Consumers MUST accept both the "&" character and the corresponding entity reference (i.e. "&") as separators between the name/value pairs as this allows Portlets to produce markup fragments valid for a larger range of mime types. We encourage Portlets to use the entity reference form ("&") in static markup as this is likely to result in the ability to include that markup in a larger set of enclosing mime types. 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 or invalidate the entire markup fragment. The Consumer is NOT REQUIRED to process escaped characters in parameter names or values, but rather MAY pass them unchanged to either the user-agent (during URL rewriting) or the Producer (during processing of an activated URL).
The following well-known portlet URL parameter names (e.g. replacing "wsrp-urlType=value", "name1" and "name2" above) are defined:
This parameter MUST be specified first when using the Consumer URL rewriting template and the value selected from the following definitions. Well-known portlet URL parameter names that are valid for only one wsrp-urlType are described relative to that wsrp-urlType while the remainder are described later. The following values are defined for wsrp-urlType:
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 defined by this specification MUST be passed to performBlockingInteraction as formParameters.
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 the overhead of two-step processing by directly invoking getMarkup. The URL MAY specify the wsrp-navigationalState and/or wsrp-navigationalValues portlet URL parameters, whose values the Consumer MUST supply in the opaqueValue and publicValues fields of the NavigationalContext structure, respectively.
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, either the wsrp-resourceID portlet URL parameter or a combination of the wsrp-requiresRewrite portlet URL parameter and at least one of the wsrp-url and wsrp-resourceID portlet URL parameters MUST also be specified. Since the Portlet is allowed to specify either both or just one of the means of getting a resource, Consumers will need to support both the transport proxy and SOAP operation mechanisms. This flexibility allows the Portlet's markup to control which resource serving mechanism is in use whenever it needs to and allows for the Portlet to provide additional guidance when both mechanisms are supported, since the fidelity of what is presented to the End-User might depend on which mechanism is selected by the Consumer.
This 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 be strictly encoded (i.e. "&", "=", "/", and "?" need to be url-escaped) so that special URL characters do not invalidate the processing of the enclosing URL. Consumers are strongly encouraged 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. Producers can set cookies with any needed data which the Consumer will then process, using the cookie rules established by RFC2109[19] , relative to forwarding these when retrieving the resource using HTTP transport.
This parameter provides the resourceID parameter which the Consumer MUST supply when invoking the getResource operation. The presence of this parameter informs the Consumer that the getResource operation is a viable means of fetching the resource requested by the Portlet's markup.
When this optional parameter (default value is "false") has a value of "true", the Portlet is indicating a preference for the Consumer to use the getResource operation to fetch the resource. If the resource URL specifies both the wsrp-url and the wsrp-resourceID parameters, the Consumer can use either the http proxy technique introduced in WSRP v1.0 or the getResource operation, but is encouraged to follow the guidance provided by this url parameter.
The value of this portlet URL parameter defines the state which the Consumer MUST send in the resourceState field of the ResourceParams structure when the URL is activated. If this parameter is missing, the Consumer MUST NOT supply a value in the resourceState field of the ResourceParams structure.
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 resources in 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 the user/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.
WSRP extensions can define additional values for the wsrp-urlType portlet URL parameter. Extensions doing so are encouraged to define extensions to the Templates structure to add templates for both normal and secure URI access using the semantics defined by the extension. Consumers supporting an extension MUST supply defined extensions to the Templates structure to those Producers indicating support for the same extension in their ServiceDescription.
The value of this portlet URL parameter defines the opaqueValue portion of the Portlet's 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 opaqueValue portion of the Portlet's navigational state.
The value of this portlet URL parameter defines updates to the publicValues portion of the Portlet's navigational state which the Portlet defined in its PortletDescription. As updates, a Portlet-defined navigationalParameter without a value on a particular URL maintains the current value the Consumer has for it while a navigationalParameter without a value defines the clearing of that parameter. Since multiple updates can be specified on a single URL, the following sequence of steps MUST be used when encoding the value for the wsrp-navigationalValues portlet url parameter:
If values are supplied for the wsrp-navigationalValues portlet URL parameter, the Consumer MUST supply those values in the publicValues field along with the values the Consumer has for the Portlet's navigationalParameters which were not referenced by the wsrp-navigationalValues portlet URL parameter .
The 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 MUST NOT supply the interactionState field of the InteractionParams structure.
Activating this URL includes a request to change the mode parameter in MarkupParams into the mode specified as the value for this portlet URL parameter. The value for wsrp-mode MUST be one of the modes detailed in [Section 6.9] 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".
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 wsrp-windowState MUST be one of the values detailed in [Section 6.10] or a custom window state the Consumer 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".
This portlet URL parameter specifies the portion of an URL that navigates to a place within a document.
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 secure communication for their current markup [A612] [R415],
Extensions to the data supplied on the URL which this protocol defines MUST use the following sequence to encode the additoinal information into the wsrp-extensions portlet URL parameter:
Here are some examples of portlet URLs following this format:
|
wsrp_rewrite?wsrp-urlType=resource&wsrp-url=http%3A%2F%2Fresource.example.com%2Fimages %2Ftest.gif&wsrp-requiresRewrite=true&wsrp-resourceID=images%2Ftest.gif/wsrp_rewrite |
|
wsrp_rewrite?wsrp-urlType=blockingAction&wsrp-secureURL=true& wsrp-navigationalState=a8h4K5JD9&wsrp-interactionState=fg4h923mdk/wsrp_rewrite |
| wsrp_rewrite?wsrp-urlType=render&wsrp-mode=help&wsrp-windowState=maximized/wsrp_rewrite |
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 take the form of a simple template, for example:
| http://Consumer.example.com/path/{wsrp-urlType}?mode={wsrp-mode}&... |
The definition of the content of this template is completely up to the Consumer. It may consist of zero or more replacement tokens. These tokens are enclosed in curly braces (i.e. "{" and "}") and contain the name of the portlet URL parameter which the Producer MUST replace (using "" for those parameters where the Producer has no value). This replacement includes the curly braces, namely; "{wsrp-urlType}" becomes "render" when that is the desired URL type. All content outside the {} pairs and all {} pairs containing tokens the Producer/Portlet does not recognize 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 those specified 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 the Consumer 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 the template(s) whole in the markup and then use this template directly when computing the dynamic portlet URL.
This 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.
Activation of the URL will result in an invocation of performBlockingInteraction. The Consumer MUST integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationalValues, wsrp-interactionState, wsrp-mode and wsrp-windowState in its template and SHOULD integrate placeholders for the other portlet URL parameters defined in this specification.
secureBlockingActionTemplate is equivalent to blockingActionTemplate, but using secure communication.
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-navigationalValues, wsrp-mode and wsrp-windowState in its template.
secureRenderTemplate is equivalent to renderTemplate, but using secure communication.
Activation of the URL will result in the Consumer fetching the underlying resource, possibly in a cached manner, and returning it to the End-User. The Consumer MUST integrate placeholders for at least the portlet URL parameters wsrp-url, wsrp-resourceID, wsrp-preferOperation, wsrp-requiresRewrite , wsrp-navigationalValues and wsrp-navigationalState wsrp-resourceState to allow the Portlet to place all the pieces of information it could use for accessing a resource. If the Portlet needs to share data with a resource when the wsrp-preferOperation has a value of "false", it can either supply the data on the URL to the resource or exploit the cookie support when the transport layer is http.
ResourceTemplate is equivalent to ResourceTemplate, but using secure communication.
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 and resource oriented templates, the Consumer SHOULD integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationalValues, wsrp-interactionState, wsrp-resourceID, wsrp-resourceState, wsrp-mode and wsrp-windowState in this template.
This 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 and resource oriented templates, the Consumer SHOULD integrate placeholders for at least the portlet URL parameters wsrp-navigationalState, wsrp-navigationalValues, wsrp-interactionState, wsrp-resourceID, wsrp-resourceState, and wsrp-windowState in this template.
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, wsrp-userContextKey, wsrp-portletInstanceKey or wsrp-sessionID in a template, Producer written URLs based on that template MUST replace the specified portlet URL parameter with the value the Consumer separately supplied in a data field.
| Portlet URL parameter | Structure name | Field name |
| wsrp-portletHandle | PortletContext | portletHandle |
| wsrp-userContextKey | UserContext | userContextKey |
| wsrp-portletInstanceKey | RuntimeContext | portletInstanceKey |
| wsrp-sessionID | SessionParams | sessionID |
These definitions utilize the syntax defined in ISO/IEC 14977 [21]
ConsumerURL = BeginToken (RenderURL | ActionURL | ResourceURL | ExtensionURL) EndToken
BeginToken = "wsrp_rewrite?"
EndToken = "/wsrp_rewrite"
RenderURL = "wsrp-urlType=render" ({("&" | "&") (CommonPair | RenderPair))*}
ActionURL = "wsrp-urlType=blockingAction" ({("&" | "&") ("&" | "&") (CommonPair | ActionPair))*}
ResourceURL = "wsrp-urlType=resource" ({("&" | "&") ("&" | "&") (CommonPair | ResourcePair))*}
WSRPURLTypes = "render" | "blockingAction" | "resource"
ExtensionURL = "wsrp-urlType=" (Text - WSRPURLTypes) {("&" | "&") (ExtensionPair)}
CommonPair = CommonTextPair | CommonBooleanPair
CommonTextPair = CommonTextName "=" Text
CommonTextName = "wsrp-navigationalState" | "wsrp-navigationalValues" | "wsrp-fragmentID" | "wsrp-extensions"
CommonBooleanPair = CommonBooleanName "=" BooleanValue
CommonBooleanName = "wsrp-secureURL"
RenderPair = RenderTextName "=" Text
RenderTextName = "wsrp-mode" | "wsrp-windowState" | "wsrp-navigationalState" | "wsrp-navigationalValues"
ActionPair = ActionTextName "=" Text
ActionTextName = "wsrp-interactionState" | RenderTextName
ResourcePair = (ResourceTextName "=" Text) | (ResourceBooleanName "=" BooleanValue)
ResourceTextName = "wsrp-url" | "wsrp-resourceID" | "wsrp-resourceState"
ResourceBooleanName = "wsrp-requiresRewrite" | "wsrp-preferOperation"
ExtensionPair = Text "=" Text
Text = { "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")" | "%" }
Text = <any URL-encoded textual characters>
BooleanValue = (("true" | "1") | ("false" | "0"))
ProducerURLTemplate = (Text* ReplacementToken*)*
ReplacementToken = "{" CommonTextName | RenderTextName | ActionTextName | ResourceTextName | CommonBooleanName | ResourceBooleanName | ParameterName "}"
ParameterName = "wsrp-urlType" | "wsrp-portletHandle" | "wsrp-userContextKey" | "wsrp-portletInstanceKey" | "wsrp-sessionID"
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 the simplest 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 activated as query string parameters. As a result, Portlets that include HTML forms with method=get in their 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. Note that the discussion in [Section 12.2] will apply to some uses of method=get in HTML forms.
Aggregating multiple Portlets from different sources can potentially result in naming conflicts for various types of elements: named attributes, JavaScript functions and variables [A303], etc. Tokens needing uniqueness on the aggregated page MUST be encoded to a Portlet-instance specific namespace [A301]. The Portlet MAY do this by prefixing the name of the itemresource with the namespacePrefix from the RuntimeContext structure. We note that the JavaScript examples exclude the possibility of starting such prefixes with a numerical character.
In order for the semantics of namespace encoding, whether by Consumer rewriting or Producer writing, to serve the purposes of making the encoded items unique on the aggregated page and processable by the Producer/Portlet, should they become part of a user interaction, the namespacePrefix from the RuntimeContext structure MUST be the value used for both Consumer rewriting and Producer writing and MUST be constant for the duration of the portletHandle. Portlets choosing to apply namespace encoding to items that become part of a user interaction MUST process these items with their namespace prefix attached as Consumers MUST NOT remove such prefixes, regardless of whether Consumer rewriting or Producer writing was used to attach the prefix. The Portlet does not need to store the value of the namespace prefix as the required semantics result in the namespacePrefix from the RuntimeContext structure supplying it to the Portlet again. Note that many things Producers and Portlets could namespace, such as CSS style names, are not required to be unique and therefore are preferably not namespaced as this adds processing burden to generate the namespacing. This likely also has an impact on client side code that may use such items to locate items on the page.
Similar to the case of URL rewriting, two options exist to obtain a namespace prefix.
The Portlet can prefix the token with "wsrp_rewrite_". The Consumer will locate such markers and MUST replace them with the same value that was supplied to the Portlet in the namespacePrefix field of the RuntimeContext structure. This prefix has been chosen such that the Consumer is able to do a single parse of the markup to both locate such markers and the URL rewrite expressions described in [Section 10.2.1]. In addition, this prefix is legal for at least the JavaScript and VBScript scripting languages and CSS class names. This permits the independent testing of most generated markup fragments.
The Portlet uses the namespacePrefix provided by the Consumer in the RuntimeContext structure to prefix these tokens in its markup.
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 to be 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's markup 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 break the entire aggregated page. Inclusion of such a tag invalidates the whole markup fragment, which the Consumer MAY replace with an error message.
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>.
There are some tags that are specifically prohibited by the HTML specification from occurring outside the <head> of the document. However, user-agent implementations offer varying levels of support. For example, current versions of Internet Explorer and Firefox 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 this description include <base>, <link>, <meta>, and <style>.
Since HTML excludes the nesting for <form> tags and Consumers could be embedding a Portlet's markup with a form, special care needs to be taken by both the Portlet and Consumer.
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>.
There are some tags that are specifically prohibited by the XHTML specification from occurring outside the <head> of the document. However, user-agent implementations offer varying levels of support. For example, current versions of Internet Explorer and Firefox 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 this description include <base>, <link>, <meta>, and <style>.
Since XHTML excludes the nesting for <form> tags and Consumers could be embedding a Portlet's markup with a form, special care needs to be taken by both the Portlet and Consumer.
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>.
There are some tags that are specifically prohibited by the XHTML Basic specification from occurring outside the <head> of the document. However, user-agent implementations offer varying levels of support. For example, current versions of Internet Explorer and Firefox 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 this description include <base>, <link>, <meta>, and <style>.
Since XHTML Basic excludes the nesting for <form> tags and Consumers could be embedding a Portlet's markup with a form, special care needs to be taken by both the Portlet and Consumer.
One of the goals of an aggregated page is a common look-and-feel across the Portlets contained on that page [A500]. This not only affects the decorations around the Portlets, but also their content. 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 Consumer-specific markup. Portlets SHOULD use the CSS style definitions from this specification in order to 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.5] of this specification.
This section defines styles for a variety of logical units in the markup.
A custom CSS class is not defined for the <a> tag. The Portlet should use the default classes when embedding anchor tags.
The font style definitions affect the font attributes only (i.e. font face, size, color, style, etc.).
| Style | Description | Example |
| portlet-font | Font attributes for the "normal" fragment font. Used for the display of non-accentuated information. | Normal Text |
| portlet-font-dim | Font attributes similar to the portlet-font but the color is lighter. | Dim Text |
If a Portlet author wants a certain font type to be larger or smaller, they should indicate this using a relative size.
Example1: <div class="portlet-font" style="font-size:larger">Important information</div>
Example2: <div class="portlet-font-dim" style="font-size:80%">Small and dim</div>
Message style definitions affect the rendering of a paragraph (i.e. alignment, borders, background color, etc.) as well as text attributes.
| Style | Description | Example |
| portlet-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 |
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-body | Normal 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 the other categories (e.g. explanatory or help text that is associated with the section). |
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-body | Normal 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 the other categories (e.g. explanatory or help text that is associated with the table). |
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 the labels 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 that appears beside a form field (e.g. input fields, checkboxes, etc.) |
| portlet-form-field | Text for a field which is not input field (e.g. checkboxes, etc) |
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 the user's pointer (typically a mouse) hovers over it |
| portlet-menu-item-hover-selected | Selected menu item when the user's pointer mouse hovers over it |
| portlet-menu-cascade | General sub-menu settings such as background color, margins, etc |
| portlet-menu-cascade-item | A normal, unselected sub-menu item |
| portlet-menu-cascade-item-selected | Selected sub-menu item |
| portlet-menu-cascade-item-hover | Normal, unselected sub-menu item when the user's pointer mouse hovers over it |
| portlet-menu-cascade-item-hover-selected | Selected sub-menu item when the user's pointer mouse hovers over it |
| portlet-menu-separator | Separator between menu items |
| portlet-menu-cascade-separator | Separator between sub-menu items |
| portlet-menu-content | Content for a normal, unselected menu or sub-menu item |
| portlet-menu-content-selected | Content for an selected menu or sub-menu item |
| portlet-menu-content-hover | Content for an unselected menu or sub-menu item when the user's pointer mouse hovers over it |
| portlet-menu-content-hover-selected | Content for a selected menu or sub-menu item when the user's pointer mouse hovers over it |
| portlet-menu-indicator | Indicator that a menu item has an associated sub-menu |
| portlet-menu-indicator-selected | Indicator when the associated menu item is selected |
| portlet-menu-indicator-hover | Indicator when the associated menu item has the user's pointer mouse hover over it |
| portlet-menu-indicator-hover-selected | Indicator when the associated menu item is selected and has the user's pointer mouse hover over it |
| portlet-menu-description | Descriptive text for the menu (e.g. in a help context below the menu) |
| portlet-menu-caption | Menu caption |
This specification provides a mechanism for Portlets to use End-User information as a means for 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; the Consumer 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 | Structure 2 | Structure 3 | Field Name |
| name/prefix | PersonName | prefix | ||
| name/given | PersonName | given | ||
| name/family | PersonName | family | ||
| name/middle | PersonName | middle | ||
| name/suffix | PersonName | suffix | ||
| name/nickname | PersonName | nickname | ||
| bdate | bdate | |||
| gender | gender | |||
| employerInfo/employer | EmployerInfo | employer | ||
| employerInfo/department | EmployerInfo | employerInfo/jobtitle | ||
| EmployerInfo | jobtitle | jobtitle | ||
| homeInfo/postal/name | Contact | Postal | name | |
| homeInfo/postal/street | Contact | Postal | street | |
| homeInfo/postal/city | Contact | Postal | city | |
| homeInfo/postal/stateprov | Contact | Postal | stateprov | |
| homeInfo/postal/postalcode | Contact | Postal | postalcode | |
| homeInfo/postal/country | Contact | Postal | country | |
| homeInfo/postal/organization | Contact | Postal | organization | |
| homeInfo/telecom/telephone/intcode | Contact | Telecom | TelephoneNum | intcode |
| homeInfo/telecom/telephone/loccode | Contact | Telecom | TelephoneNum | loccode |
| homeInfo/telecom/telephone/number | Contact | Telecom | TelephoneNum | number |
| homeInfo/telecom/telephone/ext | Contact | Telecom | TelephoneNum | ext |
| homeInfo/telecom/telephone/comment | Contact | Telecom | TelephoneNum | comment |
| homeInfo/telecom/fax/intcode | Contact | Telecom | TelephoneNum | intcode |
| homeInfo/telecom/fax/loccode | Contact | Telecom | TelephoneNum | loccode |
| homeInfo/telecom/fax/number | Contact | Telecom | TelephoneNum | number |
| homeInfo/telecom/fax/ext | Contact | Telecom | TelephoneNum | ext |
| homeInfo/telecom/fax/comment | Contact | Telecom | TelephoneNum | comment |
| homeInfo/telecom/mobile/intcode | Contact | Telecom | TelephoneNum | intcode |
| homeInfo/telecom/mobile/loccode | Contact | Telecom | TelephoneNum | loccode |
| homeInfo/telecom/mobile/number | Contact | Telecom | TelephoneNum | number |
| homeInfo/telecom/mobile/ext | Contact | Telecom | TelephoneNum | ext |
| homeInfo/telecom/mobile/comment | Contact | Telecom | TelephoneNum | comment |
| homeInfo/telecom/pager/intcode | Contact | Telecom | TelephoneNum | intcode |
| homeInfo/telecom/pager/loccode | Contact | Telecom | TelephoneNum | loccode |
| homeInfo/telecom/pager/number | Contact | Telecom | TelephoneNum | number |
| homeInfo/telecom/pager/ext | Contact | Telecom | TelephoneNum | ext |
| homeInfo/telecom/pager/comment | Contact | Telecom | TelephoneNum | comment |
| homeInfo/online/email | Contact | Online | ||
| homeInfo/online/uri | Contact | Online | uri | |
| businessInfo/postal/name | Contact | Postal | name | |
| businessInfo/postal/street | Contact | Postal | street | |
| businessInfo/postal/city | Contact | Postal | city | |
| businessInfo/postal/stateprov | Contact | Postal | stateprov | |
| businessInfo/postal/postalcode | Contact | Postal | postalcode | |
| businessInfo/postal/country | Contact | Postal | country | |
| businessInfo/postal/organization | Contact | Postal | organization | |
| businessInfo/telecom/telephone/intcode | Contact | Telecom | TelephoneNum | intcode |
| businessInfo/telecom/telephone/loccode | Contact | Telecom | TelephoneNum | loccode |
| businessInfo/telecom/telephone/number | Contact | Telecom | TelephoneNum | number |
| businessInfo/telecom/telephone/ext | Contact | Telecom | TelephoneNum | ext |
| businessInfo/telecom/telephone/comment | Contact | Telecom | TelephoneNum | comment |
| businessInfo/telecom/fax/intcode | Contact | Telecom | TelephoneNum | intcode |
| businessInfo/telecom/fax/loccode | Contact | Telecom | TelephoneNum | loccode |
| businessInfo/telecom/fax/number | Contact | Telecom | TelephoneNum | number |
| businessInfo/telecom/fax/ext | Contact | Telecom | TelephoneNum | ext |
| businessInfo/telecom/fax/comment | Contact | Telecom | TelephoneNum | comment |
| businessInfo/telecom/mobile/intcode | Contact | Telecom | TelephoneNum | intcode |
| businessInfo/telecom/mobile/loccode | Contact | Telecom | TelephoneNum | loccode |
| businessInfo/telecom/mobile/number | Contact | Telecom | TelephoneNum | number |
| businessInfo/telecom/mobile/ext | Contact | Telecom | TelephoneNum | ext |
| businessInfo/telecom/mobile/comment | Contact | Telecom | TelephoneNum | comment |
| businessInfo/telecom/pager/intcode | Contact | Telecom | TelephoneNum | intcode |
| businessInfo/telecom/pager/loccode | Contact | Telecom | TelephoneNum | loccode |
| businessInfo/telecom/pager/number | Contact | Telecom | TelephoneNum | number |
| businessInfo/telecom/pager/ext | Contact | Telecom | TelephoneNum | ext |
| businessInfo/telecom/pager/comment | Contact | Telecom | TelephoneNum | comment |
| businessInfo/online/email | Contact | Online | ||
| businessInfo/online/uri | Contact | Online | uri |
Portlets that need access to user information declares in its metadata the specific user profile fields it needs using the names specified above.
Consumers supplying additional custom profile fields are encouraged to publish a similar mapping between userProfileItems and the custom fields.
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).
Mechanisms that support federation of user identity between web service systems are defined in other specifications, such as WS-Security and SAML. If a Consumer and Producer need to share a common identity for an End-User, it is recommended that compliance with these standards be the means to passing the required information [A602].
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 can request 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) [A603].
For the purpose of interoperability, the following extension items are defined. Each definition includes the types it is allowed to extend.
This extension is of type QNamedString from the urn:oasis:names:tc:wsrp:extra:v1 namespace with a name of "wsrp-extra:doctype" with the value carrying the doctype URI. The URIs to use as doctypes have been defined elsewhere (e.g. http://www.w3.org/TR/html4/struct/global.html#h-7.2 ). This extension can apply to both the MarkupParams (specifying an allowed doctype to the Portlet) and the MarkupContext (specifying the actual doctype of the markup being returned) types.
This extension applies to MarkupParams, InteractionParams and ResourceParams and provides a standardized means for carrying name/value pairs from an activated URI which were not either consumed by the Consumer's processing or reflected elsewhere within the protocol. The type of this extension is wsrp:NamedStringArray. Consumers should take care with regard to how user-agents encode this data. In particular, common user-agents (e.g. web browsers) encode the data in the character set of the page submitting the URI. 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 the data is properly decoded before it is passed to the Producer.
Consumers MUST send the value received for the wsrp-urlType portlet URL parameter using the name "wsrp-urlType" as the first element in the array of name/value pairs. Consumers MUST NOT resend a particular set of wsrp-extra:extendedURLParameters on later invocations of WSRP defined operations. Portlets needing any of the supplied data in order to properly rerender their markup are responsible for storing that data between requests.
Examples of intended use for this extension include:
| Type | Value | Description |
| Mode | wsrp:view | Portlet is expected to render markup reflecting its current state. |
| Mode | wsrp:edit | Portlet is expected to render markup useful for End-User customization. |
| Mode | wsrp:help | Portlet is expected to render markup useful for helping an End-User 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 page layout. |
| Window state | wsrp:normal | The Portlet is sharing space with other Portlets and should restrict its consumption of space accordingly. |
| Window state | wsrp:minimized | The Portlet, though still aggregated on the page, is expected to restrict its consumption of space to a bare minimum. |
| Window state | 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. |
| Window state | wsrp:solo | The Portlet is the only Portlet being rendered on the Consumer's aggregated page. |
| Events | wsrp:eventHandlingFailed | This event is used to signal that the Consumer has detected that event processing encountered an error. |
| Events | wsrp:newNavigationalContextScope | This event is used to signal that Consumer has determined that a new scope is starting for the Portlet's navigationalContext. This enables those Portlets making technology choices which require either the Producer or Portlet to store/manage a portion of the overall state related to navigation to manage that portion in a manner consistent with the Consumer's management of this state for other Portlets. |
In addition to generic fault messages that may be generated by the web service stacks of the Consumer and/or Producer, a variety of messages specific to this protocol are defined. The following WSRP error codes are defined within the same namespace as the rest of the types defined by this specification. The SOAP 1.1 faultcode SHOULD be set to the WSRP error code being raised, namespace qualified to be in the "urn:oasis:names:tc:wsrp:v1:types" namespace. In addition, the SOAP 1.1 fault's detail element MUST contain the corresponding namespaced fault element from the WSRP v1 WSDL as its only content. When using SOAP 1.2, the Subcode element MUST be present and carry the corresponding WSRP error code in its mandatory Value sub-element. The Subcode element MUST be contained in a SOAP 1.2 Receiver fault code, for the fault messages defined in this specification. SOAP 1.2 faults MAY carry additional content in the Detail sub-element, but MUST carry the corresponding WSRP namespaced fault element.
| Fault Code | Description |
| AccessDenied | Policy has denied access. This may be related to the Consumer's registration |
| ExportByValueNotSupported | The Consumer required exportByValue, but the Producer does not support this feature |
| ExportNoLongerValid | The export references itemresources which are not on the Producer |
| InconsistentParameters | Used when a Consumer supplies inconsistent parameters (e.g. when a portletHandle is not scoped by the supplied registrationHandle). |
| InvalidRegistration | Used when a Consumer supplies a registrationHandle/registrationState pair that is not recognized by the Producer. This includes when no registrationHandle is supplied, but a registration is required. |
| 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. |
| InvalidHandle | Used when the Consumer supplies an invalid Handle |
| InvalidSession | Used only when a Producer session has timed out and the Producer needs the Consumer reinvoke the operation resending user profile and URL templates that may have been stored in the Producer session. If both userContextStoredInSession and templatesStoredInSession fields of the PortletDescription type are "false", Producers are encouraged to reinitialize the session in stead of returning the InvalidSession fault. |
| InvalidUserCategory | The specified userCategory is not supported |
| ModifyRegistrationRequired | Used when a modification to the information supplied during registration is required in order to continue using the registration |
| MissingParameters | Used when required parameters are missing |
| OperationFailed | Normal execution of the operation failed. Check the detailed message for reasons why. |
| OperationNotSupported | The Producer does not support the optional feature enable by the operation |
| ResourceSuspended | The indicated resource is no longer available for normal use, but is available for renewal |
| PortletStateChangeRequired | Used when a Portlet needs to modify its enduring state, but has been prevented from doing so. |
| UnsupportedLocale | The Portlet does not support generating markup for the requested locale. Since the Portlet is not required to generate 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 the requested locales. The Consumer can treat this as a specialization of the OperationFailed fault message and does not have to retry getting the markup in other locales. |
| UnsupportedMimeType | The Portlet does not support generating markup for the requested mime type |
| UnsupportedMode | The Portlet does not support generating markup for the requested mode |
| UnsupportedWindowState | The Portlet does not support generating markup for the requested window state |
Normative copies of the WSDL that MUST be referenced by Producers implementing this specification can be found at:
http://www.oasis-open.org/committees/wsrp/specifications/version2/wsrpv2types.xsd http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-types.xsd - The type, message and fault definitions for this specification. These definitions form the "urn:oasis:names:tc:wsrp:v2:types" namespace.
http://www.oasis-open.org/committees/wsrp/specifications/version2/wsrpv2interfaces.wsdl http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-interfaces.wsdl - The portType definitions for this specification. These definitions form the "urn:oasis:names:tc:wsrp:v2:intf" namespace.
http://www.oasis-open.org/committees/wsrp/specifications/version2/wsrpv2bindings.wsdl http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-bindings.wsdl - The standard binding definitions for this specification. These definitions form the "urn:oasis:names:tc:wsrp:v2:bind" namespace.
While this version of the WSRP specification does not define bindings for serializing some portions of the messages using the [MTOM] specification, it is expected these will be defined as an errata item once web stack support allows for interoperability testing using the definitions.
In addition the TC has provided definitions in http://www.oasis-open.org/committees/wsrp/specifications/version2/wsrp_extra.xsd http://docs.oasis-open.org/wsrp/wsrp-extra-2.0.xsd for reuse in extension elements.
This WSDL defines the following portTypes:
This WSDL defines the following SOAP bindings for these portTypes:
Producers SHOULD NOT expect Consumers to use a mixture of WSRP v1 and v2 ports when interacting with it. Producers SHOULD use a single wsdl file with distinct service elements for their v1 and v2 support if they support artifacts, such as registrationHandle or portletState, being used with all operations regardless of the version of the standard defining that operation and SHOULD use separate wsdl files for specifying support for different versions of WSRP when artifacts are usable only within the operations defined by a specific version of the WSRP standard.
| Action | A 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 the object. Objects' attributes are often specified in terms of their physical traits, such as size, shape, weight, and color, etc., for real-world objects. Objects in cyberspace 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. |
| Client | A system entity that accesses a web service. |
| Consumer | A 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
|
| Portlet | Producer hosted component that generates content design for aggregating and processes interactions generated from that content. |
| Producer | A web service conforming to this specification. |
| Session | A finite duration interaction between system entities, often involving a user, typified by the maintenance of some state of the interaction for the duration of the interaction. |
| System Entity | An active element of a computer/network system. For example, an automated process or set of processes, a subsystem, a person or group of persons that incorporates a distinct set of functionality. |
| Time-Out | A period of time after which some condition becomes true if some event has not occurred. 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 the Internet." 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 the client device. |
| Web Service | A Web Service is a software component that is described via WSDL and is capable of being accessed via standard network protocols such as but not limited to SOAP over HTTP. |
| Web Site | A 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 by consuming applications
- WSRP services can be published, found, and bound in a standard manner, describing themselves with standardized metadata |
| XML (Extensible Markup Language) | 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, the Standard 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 as element types and attribute names. An XML namespace is often associated with an XML schema. See http://www.w3.org/TR/REC-xml-names/ . |
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.
To ease the mapping of End-Users to user categories and to facilitate plug-and-play, the following 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.
This specification defines a number of types of state and state-passing mechanisms. The following table is an attempt to elucidate the differences between these in one place:
| Type of state | Comments |
| interactionState | This type of state is encoded by Portlets in interaction URLs generated by the Portlet, and is supplied to the Portlet by the Consumer when the End-User activates the URL. |
| uploadData | Data the End-User is uploading to the Portlet. |
| formParameters | Name/value pairs the End-User is supplying to the Portlet, usually via a form submission. |
| Navigational state |
This type of state is intended to support page reloads (including from bookmarks)
without the view generated by the Portlet changing in a manner unexpected by the
End-User. The Consumer resupplies a portlet's most recent navigational state on
relevant operations. The Portlet may return the values it wants to be supplied
in the future on the response from relevant operations or encode such values in
URLs such that they get applied when the URL is activated.
The two aspects of this type of state are:
|
| Session state | This type of state provides for communication between the Producer and Consumer regarding transient state that is instantiated and managed on the Producer. Either can invalidate this state as part of their normal processingresource handling (The Producer by destroying the session and the Consumer by not supplying the session information on future operations). This session state defined by this protocol is opaque to the Consumer and reflected in the protocol in the sessionID fields. The Producer returns a value for the sessionID whenever a new session is created and the Consumer returns it for future operations to enable use of the session for processing a request. |
| portletState | This state reflects customizations relative to a particular use of a Portlet. This tends to have a long span and therefore be stored in a manner that is unaffected by the Producer application being stopped and restarted. Note that this type of state only appears in the protocol when the Consumer is tasked with managing it for the Producer, but conceptually applies even when the Producer manages the storage of the state. |
| registrationState | This state reflects the business and technical relationship between the Producer and Consumer. Note that this type of state only appears in the protocol when the Consumer is tasked with managing it for the Producer, but conceptually applies even when the Producer manages the storage of the state. |
| exportContext | This contains shared state for a set of exported Portlets. |
| exportState | This contains state specific to a particular exported Portlet. |
This specification defines a number of coordination mechanisms. The following table is an attempt to elucidate the differences between these in one place:
| Coordination Mechanism | Comments |
| Events | Events provide a notification mechanism that something has occurred. This notification may, but is not required to, carry data related to the notification. |
| publicValues |
This portion of a Portlet's navigational state is intended to support Consumer-mediated sharing of values across multiple Portlets. The value for any particular publicValue may be supplied by a Portlet to the Consumer at any of the times where the opaque portion of navigational state can be supplied. Consumer policy controls when values derived from sources other than the Portlet impact one of these items. Note that navigational state is stored and managed on the Consumer and therefore all components of this state (incuding publicValues are included on operations where any of it is included. |
| Producer-mediated coordination | While not strictly defined by this specification, the groupID parameter is intended as an enabling means for Producer-mediated coordination between a set of Portlets deployed just on that Producer. |
Alphabetical listing of the defined data structures along with section numbers.
The following individuals were voting members of the WSRP technical committee during the development of this specification:
| Polina Alber, Novell |
| Subbu Allamaraju, BEA Systems Inc. |
| Olin Atkinson, Novell |
| Atul Batra, Sun Microsystems |
| Wesley Budziwojski, Sun Microsystems |
| Rex Brooks, Individual |
| Mike Caffyn, NetUnity Software |
| Andrew Datars, Microsoft Corporation |
| Michael Freedman, Oracle Corporation |
| Stefan Hepper, IBM Corporation |
| Richard Jacob, IBM Corporation |
| Andre Kramer, Citrix Systems, Inc |
| Dan Machak, Tibco Software, Inc. |
| Satish Ramaswamy, Vignette Corporation |
| Rich Thompson, IBM Corporation |
[1] http://www.oasis-open.org/committees/wsia/use_cases/index.shtml
[2] http://www.w3.org/TR/xforms/
[3] http://www.w3.org/TR/xmlschema-1/#xsi_type
[4] http://www.ietf.org/rfc/rfc2109.txt
[5] http://www.w3.org/TR/xmlschema-1/#xsi_type
[6] http://www.ietf.org/rfc/rfc2616.txt
[7] http://lcweb.loc.gov/standards/iso639-2/langcodes.html
[8] http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
[9] http://lcweb.loc.gov/standards/iso639-2/langcodes.html
[10] http://www.iso.org/iso/en/prods-services/iso3166ma/index.html
[11] http://www.iana.org/assignments/media-types/
[12] http://www.ietf.org/rfc/rfc2616.txt
[13] http://www.iana.org/assignments/character-sets
[14] http://www.ietf.org/rfc/rfc1522.txt
[15] http://www.ietf.org/rfc/rfc1522.txt
[16] http://www.ietf.org/rfc/rfc2109.txt
[17] http://www.cs.utexas.edu/users/moore/best-ideas/string-searching/
[18] http://www.w3.org/TR/html40/charset.html - doc-char-set
[19] http://www.ietf.org/rfc/rfc2109.txt
[20] http://www.ietf.org/rfc/rfc3986.txt
[21] http://standards.iso.org/ittf/PubliclyAvailableStandards/s026153_ISO_IEC_14977_1996(E).zip
[RDT3] Will need to validate that we can have such static URLs for v2.
[RDT4] With an update planned, change ref to newest version.