+

Search Tips   |   Advanced Search

URL generation in WebSphere Portal

URL generation in WebSphere Portal Portal URLs do not look like plain HTTP server URLs over a simple file system. Portal URLs have a complex structure and include a large compressed and encoded XML Navigation State document. The stream of random characters in a Portal URL is the Navigation State document. Full Portal function depends on correctly maintaining this Navigation State document during all the operations a user might do in Portal. Forcing Portal URLS to look like plain HTTP server URLs over a simple file system structure cripples the function of WebSphere Portal.

Some of the use cases that must be supported by Portal URLs include

  • Backward and Forward button support

    The user can use the browser's back and forward buttons to switch between recent views.

  • Bookmark-ability

    The current view can be saved into a client-side bookmark and can be accessed at any time. The user might need to log on first before they can access the bookmark. The bookmark must remain valid across portal versions.

  • Crawl-ability

    Web-Crawlers such as Googlebot can crawl portal pages and index them.

  • Cacheability

    Views of pages must be cacheable.

  • Non-Functional requirements

    Non-functional requirements include RFC 1738 URL size limitations, URL generation performance, and markup size management when markup contains many Portal URLs.

A Portal URL can be self-contained, or can be a delta URL relative to a base. A Portal URL might contain human-readable tokens for URL Mappings, Friendly URLs, Vanity URLs, or Virtual Portal context, in addition to the encoded Navigational State document.


Types of Portal Urls

Generating Portal URLs correctly is one of the most important tasks in programming a WebSphere Portal based application.

There are several different types of Portal URLs depending on what task we are trying to accomplish

  • Render URLs

    Retrieve a general view of a Portal page. It specifically does not include any portlet actions or cause any server-side state changes. A Render URL corresponds to an HTTP GET operation and is idempotent, that is, it can be run more than once without any harm. Normal WebSphere Portal page navigation is made up of render URLs.

  • Action URLs

    Used for activities within portlets. The URLs correspond to HTTP POST or PUT and are often non-idempotent, meaning they must be run at most once. An Action URL typically targets a specific portlet, and might cause server-side state changes. The portlet action and the portlet at which the action is targeted are carried as parameters within the Navigation State document.

  • Piece-of-Content URLs

    Piece-of-content URLs or PoC URLs are late binding mechanism that targets content instead of Portal artifacts such as pages.


    Methods for generating Portal URLs

    The complexity of a WebSphere Portal URL makes them difficult to hand-code. The design intention is that most self-referential URLs in Portal are generated in code at run time.

    WebSphere Portal makes several options available to a programmer for generating these complex Portal URLs. These different options are designed to address different use-cases, from the simplest to the most complex.

    • JSR 286 Portlet API and corresponding JSP tags.
      • Or if necessary when you modify an existing portlet, and upgrading is not a possibility, the older JSR 168 Portlet API.
      • The IBM Portlet API is no longer supported. Older portlets written to this API must be migrated to the latest standard.

    • IBM WebSphere Portal convenience API and corresponding JSP tags for some common use-cases not covered by JSR 286 Portlet API.

    • Cooperative Portlet API for interoperability with JSR 168 portlets.

    • Navigational State API.

    • Portlet communication


    URL Generation methods for different use cases

    Task (Simplest to most Complex) URL Generation Method
    Page navigation between Portal pages at the theme level. For example, standard tabbed pages navigation. These URLs are typically simple render URLs.
    A JSR 286 portlet, self contained (no inter-portlet communication required), generating action URLs to itself and setting its own render parameters. Portlet API: javax.portlet.*

    PortletResponse.xxx()

    portletRequest.xxx()

    built-in JSP tags 

    <%@ taglib uri="http://java.sun.com/portlet"
Prefix="portlet"%>

    render URL 

    <a href="<portlet:renderURL>
<Portlet:param name="tab"
value="tab-2"/>
2nd Tab</a>

    action URL: 

    form method="POST"
action="<portlet:actionURL/>">

    In exceptional cases, use the portlet action URL State Handling API import com.ibm.portal.state.* and see com.ibm.portal.state.accessors.portlet.PortletTargetAccessorController

    A JSR 286 portlet, which requires inter-portlet communication with another JSR 286 portlet, but no page navigation (Portal view remains on the current page). Portlet API, built in JSP tags. Inter-portlet communication might or might not require special URL generation. Publishing and subscribing messaging events do not require URL handling, but public render parameters would.
    A JSR 286 portlet, which needs to interoperate with a JSR 168 portlet. Portlet API, built in JSP tags. IPC between JSR 286 and JSR 168 does not require special URL generation handling.
    A JSR 286 portlet, which needs to

    generate a render link to another Portal page (causes page navigation)
    optionally control the mode or window state of the targeted portlet
    optionally control the Portal state
    optionally control the render parameters of the targeted portlet
    optionally control the locale for the generated request

    		Portal URL Generation Convenience API (PortalURLWriter through PortalURLGenerationService)

    For common use cases, there exists an easy-to-use convenience API This convenience API supports render URLs only. No state changes (action URLs) can be generated using this API. com.ibm.portal.portlet.service.url.PortalURLGenerationService com.ibm.portal.portlet.service.url.PortalURLWriter is the real convenience API. The service is required to get the writer where useful methods for generating URLs are available. <portlet-ext:portalRenderURL>

    A JSR 286 portlet, which needs to generate an action URL to a second specific portlet Navigational State API

    URL generation using the Navigational State SPI

    Navigational state represents the view of the portal associated with a particular client. The client can request (query) different views by interacting with the web page, for example by going to a new page. This interaction does not change the state on the server but requests a new view from the server. It is therefore a "safe" operation in terms of HTTP 1.1 (See RFC 2616, Section 9.1.1). This interaction allows the client to go back and forward through its recent views, bookmark views, and go back to them by calling a browser bookmark. This behavior is achieved by encoding the navigational state of IBM WebSphere Portal into the URL. Different navigational states result in different URLs.


    Parent Developing