WSRP Specification and Alignment


The WSRP specification (WSRP specification version 1, 2003) requires that every producer implement two required interfaces, and allows optional implementation of two others:
1. Service Description Interface (Required): This interface allows a WSRPproducer to advertise services and its capabilities to consumers. A WSRP consumer can use this interface to query a producer to discover what user-facing services the producer offers. Furthermore, the description also contains additional metadata and technical capabilities of the producer. The producer’s metadata might include information about whether the producer requires registration or cookie initialization before a consumer can interact with any of the remote portlets. For the consumer, this interface can be used as a discovery means to determine and localize the set of offered remote portlets.
2. Markup Interface (Required): This interface allows a consumer to interact with a remotely running portlet supplied by the producer. For example, a consumer would use this interface to perform some interaction when an end-user submits a form from the portal page. Since this interface supports the notion of the state, the portal might obtain the latest markup based onthe current state of the portlet (for example, when the user clicks refresh button or interaction with another portlet on the same page takes place).
3. Registration Interface (Optional): This interface serves as a mechanism for opening a dialogue between the producer and consumer so that they can exchange information about each others’ technical capabilities. The registration interface allows a producer to ask consumers to provide additional information before they start interaction with the service through the service description interface and markup interfaces. This mechanism enables a producer to customize its interaction with a specific type of consumer. For example, a producer may use a filter and reduce the number of offered portlets for a particular consumer.
4. Portlet Management Interface (Optional): This interface gives the consumer control over the life-cycle methods of the remote portlet. A consumer acquires the ability to customize a portlet’s behavior, or destroy an instance of a remote portlet using this interface.

Processing User Interaction

When the user clicks on a link or submits form data, the consumer application controls the processing and invokes the performInteraction() method (Figure 1). When the producer receives this call, it processes the action and returns the updated state. To redraw the complete page, the consumer then invokes the getMarkup() call to receive the latest markup fragment. Because the state ofthe producer has changed since the previous getMarkup() call, the markup fragment returned is typically different from the one previously returned. The end user can then perform another action, which starts a new interaction cycle.
Figure 1. Remote portlet interaction in View and Action modes
Remote portlet interaction in View and Action modes

Handling Customization and Initialization

In a typical interaction, a single centrally hosted services are used by multiple consumer applications and/or multiple individual users. The WSRP protocol supports multiple configurations of a single service. A good example is a lookup in a remote list of the course offerings and subjects offered within a particular course to international students. The list can be configured to display different offerings per semester, different currencies for subject fees, or both, depending on the consumer country and language prerequisites.
The WSRP protocol provides a set of function calls that allow producers to expose multiple versions of the same service, each with different preconfigured interface. Furthermore, consumers can create and manage additional configurations of the same service, and end users can customize their configurations. However, such configurations are static (predefined) only in the current version of WSRP 1.0. dynamic configuration is planned for the future versions of WSRP, starting with the WSRP 2.0.


Service description interface enables the consumer to determine what services are available, and also provides information about the service capabilities. The services can be discovered through UDDI or other public registry. The access to the producer metadata is provided through getServiceDescription()method.All producers must provide the service description. This is important because it affects the decision whether the portal can display the markup, cookies handling, registration requirements, and so forth. In addition, the service description also includes the access to the information about portlet capabilities: supported portlet modes, window states, and list of locales the portlet supports. The service description structure supports also an extension field. This is an Array of objects that allow both client and server to support custom features. The ServiceDescription object contains useful information for the consumer, such as whether the registration is required, list of offered portlets, need to initialize cookies, and list of resources. The list of allowed types for ServiceDescription structure is in Figure 2.
Figure 2. ServiceDescription structure
ServiceDescription structure
ItemDescription is a set of arrays used to describe custom items the consumer is allowed to use in interaction with the portlets at the producer location. Each of these arrays provides the description of different types of extended data (e.g., custom modes). For those areas where this information is provided, portlets are not allowed to use extended values the producer has not described. This restriction allows the administrator of the consumer to determine a mapping of these values to those supported by the consumer implementation.
The information about portlets that the producer hosts is available as an array of PortletDescription(s), each of which describes single offered portlet. The description of each portlet listed in offeredPortlets[] array can be obtained by invoking getPortletDescription() method. This interface allows the consumer access to the following information:
• The consumer references this portlet using portle-tHandle;
• Markup types this portlet can generate in the array markupTypes. For each markup type, the supported modes, window states, and locales are specified;
• The portlet functionality is stored in the description field;
• Title describing this portlet is stored in the shortTitle type;
• Possible (x)html forms generation availability; and
• Information about the usage of URL templates.
The producer must expose one or more logically distinct ways of generating markup and handling interaction with this markup (Figure 3).
The boolean field usesMethodGet was added to this metadata due to the difficulties introduced by means in which browsers handle query string in GET request method. It suggests that the portlet will or will not generate any (x)html forms using GET methods to submit the input data. The query string is the part of the URL following the question mark. The browsers tend to drop any query string on the URL to be submitted before generating a query string reflecting the consumer input data in the form”s fields. Many consumers may prefer to encode information, such as which portlet is to receive this information within the query string, as well as the knowledge whether or not the portlet should be handled in a special manner. While there are many options available to consumers for handling these types of portlets, typically some form of encoding this information into the path of submitted URL is required.
Figure 3. Portlet description structure
Portlet description structure

MarkupType Structure Details

The MarkupType structure is used to carry portlet metadata of mime type. The important members of this structure are portlet modes and windowStates, which reflect the same structures in portlet specification (). Portlet renders different content and performs different activities depending on its state and the operation currently being processed. Part of basic responsibilities of any portal container is support portlet interactions and correctly handle portlet modes. Port-lets may request mode changes or some modes may not be supported by the portlet. During two operations, getMarkup() and performBlockingInteraction(), the consumer indicates to the portlet its current mode.
Portlet modes are properties of the producer’s portal presentation model. Portlet modes allow the portlet to display a different “face” depending on its usage. There are four modes supported by the WSRP protocol:
1. VIEW (wsrp:view) mode is to render markup reflecting the current state of the portlet.
2. HELP (wsrp:help) mode supports the help mode, and a help page can be displayed for the user.
3. EDIT (wsrp:edit) mode produces markup to enable the user to configure the portlet for their personal use.
4. PREVIEW (wsrp:preview) mode renders its standard view mode content as a sample of current configuration.
5. The Extension array provides some space for additional custom modes.
Portlet window states (windowStates) are specified in PortletDescription data structure mentioned previously. They determine how the portlet is displayed in the portal during the aggregation stage. The consumer has to inform the producer about window states used in the aggregated portal pages. Four states of a portlet (to be precise the portlet window states) are:
1. Normal (wsrp:normal): The portlet is displayed in its initial state and size as defined when it was installed.
2. Maximized (wsrp:maximized): The portlet view is maximized and takes over the entire body of the portal, replacing all the other portal views.
3. Minimized (wsrp:minimized): The portlet should not render visible data.
4. Solo (wsrp:solo): Indicates that the portlet is the only portlet being rendered in the aggregated page. Note that not all portal vendors support this mode.
The portlet modes and window states are accessible from the portlet window title bar. As with local portlets, clicking on these icons can change the portlet’s mode.


The registration interface (Figure 4) is used by the producers to allow in-band registration of consumers to provide all necessary information during the registration process. The producers can also offer out-of-band processes to register a consumer. Both processes provide the unique handle reg-istration Handle, which refers to the remote portlet context (RegistrationContext). It is returned by the register() operation during the establishment of consumer-producer relationship. The registration can be modified using modify Registration(). The relationship between consumer and producer ends when one of them successfully invokes deregister() operation.
Figure 4. Optional registration interface
Optional registration interface
It is important to understand the difference between in-band and out-of-band registration. The consumer can register through the WSRP registration port type1 using register() call. The consumer provides all required information to the producer before any service invocation is carried out. In out-of-band registration, the consumer’s administrator must manually obtain the registration handle from the producer’s administrator. The out-of-band registration is not standardized in WSRP.


The markup interface must be implemented by all interactive user-facing interfaces to comply with WSRP standard. The operations defined by this interface allow the consumer to request the generation of markup, as well as processing of interactions with his markup. The Markup Interface structures contain important information for handling sessions, runtime, and portlet modes.
The consumer requests the markup for rendering the current state of a portlet by invoking the getMarkup() method and in return, it receives the structure called MarkupResponse. The MarkupResponse is a structure containing various information about markup context and session needed to render valid markup (Figure 5).
The format of the call getMarkup() is:
The SessionContext contains information about sessionID and its expiration time. The sessionID enables the consumer to maintain the consumer portlet state as if it was the local portlet. The RuntimeContext defines a collection of data required for end-user authentication: userAuthentication (password information), portletInstanceKey (reference to the RegistrationContext), namespacePrefix, templates used to generate the URL pointing back to the requesting application, and sessionID. The PortletContext structure is used to supply the portlet information relevant to the consumer using this portlet. It also contains portlet state, thus providing portlet state required persistency.
Figure 5. MarkupResponse structure
MarkupResponse structure


URLs need to point back to the consumer so that the consumer can supply any stateful data needed for interacting with the clone portlet. The consumer has to direct the interaction to the original producer portlet. This interaction pattern results in the scenario where the original portlet knows the details needed for this particular URL while the consumer controls the overall format and target of such URLs. WSRP provides two solutions for this problem: URL rewriting at the consumer site, and URL templates.
Consumer URL rewriting uses a specification-defined format for URLs that allows the consumer to find (for example, by parsing) and replace the URL. All portlets’ URLs are demarcated in the markup by the start tag <wsrp_rewrite> and end tag </wsrp_rewrite>. All value/pair data are placed within these tags.
Producer URL rewriting is made simpler by the WSRP specification that introduces URL templates. The portlet has to specify whether or not it is willing to do template processing as the means to generate proper URLs. This effectively means that the consumer delegates the need to parse the markup to the producer.
Another aspect of generating proper URL is related to the action the consumer should activate when the URL is activated. WSRP specification defines a portlet url parameter called wsrp-urlType to carry this information. This parameter must be specified first when using the consumer URL rewriting template. The wsrp-urlType can have several values. We mention only the following three values, but for more details, you can consult the WSRP specification (WSRP specification version 1, 2003).
1. wsrp_urlType = blockingAction is the information for the consumer that this interaction is a logical update of the portlet’s state and it must invoke performBlock-ingInteraction() method.
2. wsrp_urlType = render informs the consumer that this is the request to render a new page from the portlet and it must invoke the getMarkup() operation.
3. wsrp_urlType = resource tells the consumer that it is acting as a proxy to get the resource (e.g., a gif picture). The consumer receives the actual URL for the resource, including any query string parameters.
Remote portlets can handle end-user interaction as well as update the persistent portlet state. The operation performBlockingInteraction()has been designed to support the situations in which the interaction may change the naviga-tionalState attribute or shared data (e.g., database content). This is a transient state and it is only passed to the original invocation and not when the markup is being regenerated (e.g., when the page is refreshed and portlets pass through the page aggregation stage).
The navigationalState attribute is used by portlets that need to store the transient data needed to generate current markup. It roughly corresponds to the concept of the URL for a Web page. Furthermore, a stateless consumer can store the navigationalState for all aggregated portlets by returning them to the client; for example, using URL to encode navigationalState. This information then can be used for handling of the next interactions.


In order for the consumer and producer to successfully exchange the information in the form of remote portlets, both parties have to adhere to one or more standards. The WSRP and JSR 168 () are already aligned in many aspects(producer or consumer). Similarities and differences are discussed next (Hepper, 2003, 2004):
1. URL encoding and creating URLs pointing to the portlet corresponds to both the consumer and producer.
2. The state of a portlet fragment is supported in WSRP under the term of navigational state and in JSR 168 with the render parameters. The portlet-rendering parameters can map to WSRP’s navigational state.
3. Storing persistent state to personalize portlet’s rendering is realized in WSRP through the properties of arbitrary types, whereas JSR 168 supports only preferences of type string or string array. This means that WSRP producers based on JSR 168 use only a subset of the WSRP functionality.
4. Information about the portal calling the portlet is called RegistrationData in WSRP, and it is the equivalent to PortalContext object in JSR 168.
As evident from this list, the portlets adhering to JSR 168 specification can be exposed and accessed via WSRP as remote services. In Table 1 we provide information about important concept realization in both WSRP and local portlet space.
Table 1. Comparison WSRP and JSR 168

Concept WSRP JSR 168 Comment
Portlet Mode: Indicates portlet in what mode to operate for a given request View, Edit, Help + custom modes View, Edit, Help + custom modes full support
Window State: The state of the window in which the portlet output will be
Minimized, Normal, Maximized, Solo + custom window states Minimized, Normal, Maximized, Solo + custom window states “Solo” is missing in the JSR, but can be implemented as a custom state;
URL encoding: To allow rewriting URLs created by the portlet Defines how to create URLs to allow rewriting of the URLs either on consumer or producer side Encapsulates URL creation via a Java object Fully compliant
Namespace encoding: To
avoid that several portlets on a page conflicting with each other
Defines namespace prefixes for consumer and producer side namespacing Provides a Java method to namespace a String Fully compliant
User — portlet interaction operations performBlockinglnteraction: blocking action processing
getMarkup: render the markup
action: blocking action processing
render: render the makup
Fully compliant
View state that allows the current portlet fragment to be correctly displayed in subsequent render calls Navigational state Render parameter Fully compliant (WSRP navigational state maps to JSR render parameters)
Storing transient state across request Session state concept implemented via a sessionID Utilizes the HTTP Web application session Fully compliant

Table 1.

Concept WSRP JSR 168 Comment
Storing persistent state to
personalize the rendering of the portlet
Allows to have properties of arbitrary types Provides String-based
Full alignment
Information about the portal
calling the portlet
RegistrationData provide information of the consumer
to the producer
PortalContext provide a Java interface to access information about the portal calling the portlet Full alignment


There are some additional issues that, in our opinion, outweigh the advantages of WSRP. Firstly, we would like to present some thoughts on security issues. WSRP does not provide any standardisation for security. It only relies on the lower-level protocols. Secured transmission depends on HTTPS. In a Web application, servlets execute in neutral environment and are responsible for validating the user’s authenticity and authority to make a specific request. Portlets operate only in the context of the portal server and cannot be called directly. The portal server is responsible for authentication and for authorizing all user access. The authentication and authorization is performed prior to the portlet’s execution. However, the portlets may perform some authorization in order to associate content with a specific user or role. Therefore, authentication is a daily concern of servlet developers, but it is optional for portlet developers. In WSRP, producers are responsible for authentication and authorisation. Remember that threats to Web services represent threats to the host system, host applications, and the entire network infrastructure.
Secondly, load balancing in WSRP is a part of the producer environment. The difficulties are associated with session maintenance. Some portal servers (e.g., WebLogic or WebSphere Portal 5) provide the environment for clustering. In such situations, it is required that the consumer supports load-balancing, replication, and fail-over to functions. The initCookie operation allows the producer to initialize cookies and return those over the HTTP response underlying the SOAP response. When a user views a page containing a remote portlet for the first time, the consumer sends an initCookie request. The underlying HTTP response contains a Set-Cookie response header. The consumer is supposed to supply this cookie with all future requests to the producer. To enable clustering at the producer, consumers are required to send an initCookie request once per user per consumer. Furthermore, the consumer is supposed to keep track of any returned cookies and supply those cookies with subsequent requests. Typically, consumer stores these cookies in itsuser’s HTTPSession, which travels with the HTTPRequest object. The consumer then is highly dependent on transport mechanism and number of cookies in HTTP.
Finally, there is also a problem with fault tolerance and application reliability. The producer detects the fault and displays an error in the portlet. Alternatively, the error is not properly detected and forwarded to the consumer’s portlet, thus resulting in the situation that portlet cannot be displayed. Developers know that such portlet behaviour does not constitute adequate error handling, but it can result in a nonrecoverable problem; consequently, taking down entire portal. It would be better if the producers adhere to some fault-handling standard so if the producer falls over, the portal page at the consumer site still renders correctly.


Traditional data-based Web services require the application to provide specific presentation logic for each Web service. The motivation for WSRP and WSIA stems out of the fact that the current approach to Web services is not suitable for remote portals. Therefore, the WSRP is intended for use with WSIA (Web Services for Interactive Applications), which is also being developed by the OASIS committee (Web Services for Interactive Applications specification (WSIA), 2005)). WSIA provides well-defined interfaces and contracts on top of the generic ones to remedy the problems posed by common presentation logic in WSRP.
The portal event handling style, interportlet, and cross-portal application communications have direct relevance to processing remote portlets. The interportlet communication between remote portlets is not expected to happen at the consumer portal. Furthermore, the WSRP 1.0 specification does not provide any details concerning communication between remote and local portlet. It is assumed that the remote Web services represent entire an application (business process) that is contextually separated from any local processing and therefore, there is no requirement to exchange messages relevant to interapplication communication. Thenext large feature planned for WSRP 2.0 is to provide a mechanism for cross-portlet communication. This mechanism will allow portlets to broadcast event information to other portlets spread across multiple producers. The key issue is the ability of portlets to post their contextual information about their interaction (state) so the other portlets than can adjust their content information accordingly and generate appropriate markup.


Portlet: A Web application that displays some content in a portlet window. A portlet is developed, deployed, managed, and displayed independently of all other portlets. Portlets may have multiple states and view modes. They also can communicate with other portlets by sending messages.
Portal: A Web application that contains and runs the portlet environment, such as application server(s), and portlet deployment characteristics.
Web Services: A set of standards that define programmatic interfaces for application-to-application communication over a network.
Web Services for Remote Portlets: Presentation-oriented Web services.

Next post:

Previous post: