Web Services for Remote Portlets Specification v2.0
Committee Specification 02
28 January 2008
Specification URIs:
This version:
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-02.html
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-02.pdf
Previous Version:
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-01.html
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-01.pdf
Latest Version:
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec.html
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec.pdf
Latest Approved Version:
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-02.html
http://docs.oasis-open.org/wsrp/v2/wsrp-2.0-spec-cs-02.pdf
Technical Committee:
OASIS Web Services for Remote Portlets TC
Chair(s):
Rich Thompson, IBM Corporation <richt2@us.ibm.com>
Editor:
Rich Thompson, IBM Corporation <richt2@us.ibm.com>
Related Work:
This specification replaces or supercedes:
Declared XML Namespace(s):
urn:oasis:names:tc:wsrp:v2:types
urn:oasis:names:tc:wsrp:v2:intf
urn:oasis:names:tc:wsrp:v2:bind
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 "Latest Version" or "Latest Approved Version" location noted above for possible later revisions of this document.
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 http://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 (http://www.oasis-open.org/committees/wsrp/ipr.php).
The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/wsrp.
Notices
Copyright © OASIS® 1993–2007. All Rights Reserved. OASIS trademark, IPR and other policies apply.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
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 section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, 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 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
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' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on 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 implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
Short Table of Contents
Table of Contents
2.7 Types of Stateful Information
2.9 Producer Mediated Data Sharing
2.10 Consumer Mediated Coordination
2.11 Information Passing Mechanisms
3.1 Service Description Operations
3.4 Portlet Management Operations
4 Service Description Interface
4.1.12 PropertyDescription Type
4.1.15 ParameterDescription Type
4.1.16 PortletDescription Type
4.1.22 ExtensionDescription Type
4.1.24 ServiceDescription Type
4.1.27 RegistrationContext Type
4.2 getServiceDescription Operation
5.1.12 NavigationalContext Type
5.1.24 BlockingInteractionResponse Type
5.1.26 HandleEventsFailed Type
5.1.27 HandleEventsResponse Type
5.2.1 Caching of markup fragments
5.4.1 performBlockingInteraction Operation
5.4.3 Updating Enduring Portlet State
5.7 Consumer Transitions across Bindings
5.8 Stateful Portlet Scenarios
5.10.1 "wsrp:normal" Window State
5.10.2 "wsrp:minimized" Window State
5.10.3 "wsrp:maximized" Window State
5.10.4 "wsrp:solo" Window State
5.11.1 wsrp:eventHandlingFailed
5.11.2 wsrp:newNavigationalContextScope
5.12.1 User Category Assertions
6.3 modifyRegistration Operation
6.5 getRegistrationLifetime Operation
6.6 setRegistrationLifetime Operation
7 Portlet Management Interface
7.1.2 DestroyPortletsResponse Type
7.1.3 PortletDescriptionResponse Type
7.1.4 PortletPropertyDescriptionResponse Type
7.1.6 CopyPortletsResponse Type
7.1.8 ExportPortletsResponse Type
7.1.11 ImportPortletsFailed Type
7.1.12 ImportPortletsResponse Type
7.1.14 GetPortletsLifetimeResponse Type
7.1.15 SetPortletsLifetimeResponse Type
7.2 getPortletDescription Operation
7.5 getPortletsLifetime Operation
7.6 setPortletsLifetime Operation
7.11 setExportLifetime Operation
7.12 setPortletProperties Operation
7.13 getPortletProperties Operation
7.14 getPortletPropertyDescription Operation
8.1 Authentication of Consumer
8.2 Confidentiality & Message Integrity
9.2.3 Extended BNF Description of URL formats
9.2.4 Method=get in HTML forms
11.2 wsrp-extra:extendedURLParameters
11.3 wsrp-extra:sharedResource
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.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” 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 14]. 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 |
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.
1.5.2.1 Portlet Management
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 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 14]. The textual portion of this specification does not contain normative statements regarding the exact syntax of XML passed between Consumer and Producer, but it does contain normative statements about the manner and order in which 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) 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 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 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 5.1.1].
WSRP defines a number of items which can use a leasing concept (scheduled destruction of the item with opportunity for extending the scheduled termination time). All such items go through three stages of availability; namely:
2.7 Types of Stateful Information
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].
2.9 Producer Mediated Data Sharing
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 4.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.
2.10 Consumer Mediated Coordination
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:
2.11 Information Passing Mechanisms
All information passing enabled by this specification is between exactly one Producer and one Consumer. Implementation of data sharing, including both policy and side effects, within 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:
3.1 Service Description Operations
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); |
| ResourceResponse = getResource (registrationContext, portletContext, runtimeContext, userContext, 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); |
3.4 Portlet Management Operations
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); |
4 Service Description Interface
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) 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 | |
| [R] 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 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] LocalizedString | displayName |
| [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: