Web Services for Remote Portlets 1.0 Frequently Asked Questions

Document identifier:

WSRP-faq-1.0

Location:

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

Editors:

Clinton Davidson, Plumtree Software <Clinton.Davidson@plumtree.com>
Christopher Coco, Vignette Corp. <christopher.coco@vignette.com>

Contributors:

Rich Thompson, IBM <richt2@us.ibm.com>
Andre Kramer, Citrix <andre.kramer@eu.citrix.com>
Subbu Allamaraju, BEA Systems <subbu@bea.com>
Richard Jacob, IBM <richard.jacob@de.ibm.com>
Scott Goldstein, Vignette Corp. <scott.goldstein@vignette.com>
Michael Freedman, Oracle <Michael.Freedman@oracle.com>
Atul Batra, Sun Microsystems Inc <Atul.Batra@Sun.COM>

Abstract:

This is the WSRP 1.0 FAQ. The purpose of this document is to provide explanation for common questions about the WSRP 1.0 specification. Although this FAQ is not normative, its question-based approach is intended as one of the starting points to WSRP for implementers and other readers. For a more in-depth introduction, readers are recommended to read the Web Services for Remote Portlets 1.0 Primer The primer explains the abstractions of the specification using sample scenarios, and provides guidance and best practices for implementers and advanced users of the WSRP Specification.

Status:

This version is a draft of the non-normative WSRP 1.0 FAQ. Comments and/or additions are much appreciated and may be emailed to wsrp@lists.oasis-open.org. If you are on wsrp@lists.oasis-open.org list for committee members, send comments there. If you are not on that list, subscribe to wsrp-comment@lists.oasis-open.org list and send comments there. To subscribe, send an email message to wsrp-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message. Copyright © 2004, 2005 The Organization for the Advancement of Structured Information Standards [OASIS

If you are on wsrp@lists.oasis-open.org list for committee members, send comments there. If you are not on that list, subscribe to wsrp-comment@lists.oasis-open.org list and send comments there. To subscribe, send an email message to wsrp-comment-request@lists.oasis-open.org with the word "subscribe" as the body of the message.

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

Table of Contents

    Overview questions

  1. What is a portlet?
  2. What is WSRP?
  3. What is the difference between WSRP and JSR-168?
  4. Why not just use Web Services? Why is another specification needed?
  5. Why should I want portlets to be remote?
  6. How do I write a WSRP portlet?
  7. What is a WSRP Producer?
  8. What is a WSRP Consumer?
  9. How does a Consumer discover a Producer and the portlets it offers?
  10. Implementation questions

  11. Why should a Producer use Registration?
  12. Why are there two means (in band and out of band) of Registration?
  13. What is the difference between a Producer offered portlet (POP) and a Consumer customized portlet (CCP)?
  14. How can I clone a portlet?
  15. How can a Producer suggest that a portlet should be explictly cloned?
  16. When do cloned portlets get destroyed?
  17. Can WSRP be used with markup other than html?
  18. Can WSRP introduce a virus into my portal?
  19. Can a WSRP portlet introduce malicious JavaScript?
  20. What mechanisms does WSRP provide to maintain runtime state?
  21. When should I use navigational state vs session state?
  22. Does WSRP have a concept of sessions?
  23. Does the WSRP protocol facilitate portlets on the same producer sharing state?
  24. Does WSRP support caching?
  25. What means does the protocol provide for storing portlet customizations?
  26. How do portlet customizations map to JSR-168?
  27. How do portlet customizations map to web parts?
  28. What can the Producer learn about the user making the request?
  29. Can a portlet call another portlet?
  30. Can a Consumer assert an anonymous user to a Producer?
  31. How can I generate Java classes from the WSRP WSDL files using Axis?
  32. How can I generate .NET classes from the WSRP WSDL files?

What is a portlet?

A portlet is a user-facing, interactive application component that renders markup fragments that can be aggregated and displayed by a portal. For example, a weather portlet that could be displayed with a stock quote portlet, or an ERP portlet from a portal vendor.

What is WSRP?

Web Services for Remote Portlets (WSRP) are presentation-oriented, interactive web services. WSRP provides a standard that enables all content and application providers to provide their services in a manner where they can easily be discovered and plugged into all compliant portals without programming effort on the portal's side. See the WSRP White Paper.

What is the difference between WSRP and JSR-168?

WSRP is a standard messaging interface for interacting with compliant UI components. JSR-168 is a standard Java interface for portlets that builds on the J2EE programming model of servlets. This is an interface between a particular Java type of UI component and its hosting container. Other differences are that JSR-168 is Java only, while WSRP is platform independent. JSR-168 generally is local while WSRP is remote. See the WSRP TC page for companies that provide mappings between JSR-168 and WSRP.

Why not just use Web Services? Why is another specification needed?

As noted in the WSRP White Paper, WSRP provides an interface to deal with issues such as Localization, Mime types, portlet modes (for example, edit, help and view modes),and window states (for example minimized, maximized, solo, and normal window states). Defining these states for each web service would be tedious and error-prone.

Why should I want portlets to be remote?

Among the reasons noted in the WSRP White Paper are ease of configuration, platform independence, and scalability. Consider the ease of consuming a weather portlet from a central site to installing, configuring, and updating a weather portlet on a number of servers.

How do I write a WSRP portlet?

The simple answer is to use the methods of a company that has implemented a Producer- see the WSRP TC Page. For example, a developer could use WSRP4J on Java, or the Microsoft WSRP Web Service Toolkit for Sharepoint or NetUnity on .NET.

What is a WSRP Producer?

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

What is a WSRP Consumer?

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

How does a Consumer discover a Producer and the portlets it offers?

The base requirement is learning the URL of the WSDL. While this could be gathered via a number of means, convenient mechanisms include directory services, such as UDDI or ebXML Registry.

Why should a Producer use Registration?

The Producer should use Registration as it allows the Producer to associate portlets and their customization data with the registered Consumer. Other possible uses of Registration are for the Producer to provide a custom set of portlets to a specific Consumer, or for the Producer to allow/deny certain capabilities to different Consumers. Registration also allows the Consumer to make the Producer aware of its capabilities, including consumerModes, consumerWindowStates, consumerUserScopes, and customProfileData. See the WSRP Primer for more details. Also see section 3.5 of the WSRP Specification for a discussion of scopes, including Registraton scope, Portlet scope, and Session scope.

Why are there two means (in band and out of band) of Registration?

In-band Registration provides a convenient method to register. In band Registration optionally allows a Consumer to specify modes (such as Edit, Help, or additional modes), window states, user scopes, and registration properties. See the WSRP Primer and section 7 of the WSRP Specification for more details. However, as the relationship between the Consumer and Producer may be arbitrarily complex, a Producer can offer other means for the Consumer to obtain a registrationHandle. Note that exposing the registration portType does not mean that only in band registration is supported.

What is the difference between a Producer offered portlet (POP) and a Consumer customized portlet (CCP)?

A Producer offered portlet is one that is described in the getServiceDescriptionResponse. Consumers cannot explicitly modify the persistent state of such portlets. A consumer configured portlet is a POP or CCP that has been cloned. Consumer configured portlets can explicitly modify their persistent state. See the WSRP Primer and also How can I clone a Portlet?

How can I clone a portlet?

A Portlet can be cloned either explicitly or implicitly. A portlet is cloned explicitly using the clonePortlet operation of the Portlet Management interface. A portlet is cloned implicitly when the Consumer sets the portletStateChange field in the performBlockingInteraction request to cloneBeforeWrite, and the Producer returns a new portletHandle in the portletContext. See section 5.2.3 of the WSRP Primer for a discussion of implicit cloning and section 6 for a discussion of explicit cloning.

How can a Producer suggest that a portlet should be explictly cloned?

A Producer can that a portlet be explicitly cloned by setting hasUserSpecificState of the PortletDescription to true. Note that setting this to false does not imply that the Portlet is not clonable. See section 5.1.12 of the WSRP Specification.

When do cloned portlets get destroyed?

Cloned portlets can be destroyed by calling the destoyPortlets operation in the PortletManagementInterface See section 8.4 of the WSRP Specification. In addition, if the cloned portlets were scoped within a registration context, those portlets will be destroyed when the deregister operation is called. See section 7.4 of the WSRP Specification.

Can WSRP be used with markup other than html?

Yes. While our examples are in html, as that is the dominant mime type, WSRP does not restrict the mime types that can be used. See the MarkupType type in the WSRP Specification for more details.

Can WSRP introduce a virus into my portal?

First, there should be some level of trust established between the Producer and Consumer during the registration process. Second, the getMarkup call usually returns a markupString in the MarkupContext type. If getMarkup returns Binary Content (markupBinary in the MarkupContext type), it is up to the Consumer implementation to interpret this binary data. The Producer is not transferring anything for execution on the Consumer. Also see Can a WSRP Portlet introduce malicious JavaScript?

Can a WSRP Portlet introduce malicious JavaScript?

First, there should be some level of trust established between the Producer and Consumer during the registration process. In most cases, an HTTP transport binding is used, and XML is transferred across the wire between Producer and Consumer. This XML most often contains markup fragments of HTML, which in turn could contain client-side JavaScript. Due to inherent client-side JavaScript limitations , it is not thought that this will be a large concern for Consumers.

What mechanisms does WSRP provide to maintain runtime state?

WSRP provides navigational state and session state. See Section 5.1.3 in the WSRP Primer for a discussion on state management. Also see section 3.6 Types of Stateful Information in the WSRP Specification.

When should I use navigational state vs session state?

Navigational state is analogous to a query string in http: the Producer does not need to hold the transient state, the state is bookmarkable by the user, and there are no timeout issues as there are with sessions. Session state is analogous to HTTP Session state management. The arguments for using one of the other are similar to that with HTTP; Session state makes it simpler to use more complicated data structures but increases memory requirements and requires dealing with session timeouts. See section 5.6 Recommendations in the WSRP Primer.

Does WSRP have a concept of sessions?

Yes. In a getMarkup call, the Producer may optionally return a SessionContext, which contains a sessionID to identify the session. This should not be confused with a session which could be established between a user-agent (browser) and a Consumer.The Consumer should supply this sessionID on future invocations of getMarkup and performBlockingInteraction in order to not lose state the Producer is storing for the user's interactions. If a Consumer does not invoke this portlet before this interval, the Producer may terminate the session associated with the sessionID. For more information, search for sessionID in the WSRP Specification.

Does the WSRP protocol facilitate portlets on the same producer sharing state?

No, the protocol does not facilitate this, although the producer can point to a larger group session in the http case. See section 3.8 Producer Mediated Sharing in the WSRP Specification. The Producer can also share state by encoding it in the sessionID and/or navigational state.

Does WSRP support caching?

Caching is supported but not required. The Consumer may support caching by using the CacheControl structure, which includes members for expiration duration, scope of cache (for all portlets, or just for this user), and a validation tag (analogous to an ETag). See section 5.5 on Caching of Markup in the WSRP Primer.

What means does the protocol provide for storing portlet customizations?

Portlet customizations can either be stored on the Producer, or returned to the Consumer as PortletState. Note that returning PortletState has a much higher network cost, as the PortletState then needs to be returned on many calls. See section 6.2.4 Clone Portlet in the WSRP Primer.

How do portlet customizations map to JSR-168?

setPortletProperties/getPortletProperties roughly map to setValue/getValue in JSR-168 PortletPreferences. An implementation could map portletProperties to portletPreferences in JSR-168, as WSRP4J does.

How do portlet customizations map to web parts?

???

Can a portlet call another portlet?

No, not in the 1.0 specification. The 2.0 specification is investigating eventing as a means to notify other portlets.

Can a Consumer assert an anonymous user to a Producer?

Yes, the best practice is to use a known unique user key for the userContextKey in the UserContext type. For example, many portals provide a specific ID for a guest user.

What can the Producer learn about the user making the request?

Section 6.1.20 of the WSRP Specification defines a UserContext type, which contains a userContextKey to uniquely identify a user. This key may map to a unique name in a directory system, e.g. a distinguished name in LDAP. The UserContext also optionally contains userCategories, which contain Producer defined categories, and a UserProfile type, which may contain profile information such as employer information and contact information. See section 6.1.19 of the WSRP Specification for more information on UserProfile.

How can I generate Java classes from the WSRP WSDL files using Axis?

Use the Axis WSDL2Java tool or the associated Ant task. Note that the -W parameter should be used to create the stubs with wrapped parameters. For all Java stacks, view the web services toolkit documentation.

How can I generate .NET classes from the WSRP WSDL files?

Use wsdl.exe. Note that all wsdl files (interface wsdl, bindings wsdl, service wsdl, and schema [xsd]) need to be listed on the command line.