You are on page 1of 54

WebSphere Portal v6

Unifying people, tools and resources for greater productivity

What you always wanted to know about URIs in WebSphere Portal or more than that
Dr. Carsten Leue (
2007 IBM Corporation
The companies and people in this scenario are fictitious. Actual user interfaces may differ from those depicted here.

WebSphere Portal v6

Why is this presentation interesting?

Because it answers these questions: Why are my portal URLs so long? (short answer: they arent ) Why do my portal URLs look like random character sequences? Are there ways to produce human readable URLs? What are the pros and cons? How can URL handling be customized? What is the concept behind URL handling in WebSphere Portal?

Typical example of a WebSphere Portal URL

http://localhost:10038/wps/myportal/!ut/p/c1/04_SB8K8xLLM9MSSzPy8xBz9 CP0os3h3g0ADYzcPIwP30GATAyNT01ADM1NzIwMDc_1wkA6z-DBvwCwAHcjQwOTAFegCmcPo1ADcwODQGOIvAEO4Gig7-eRn5uqX5CdneboqKgIANkbCCk!/

WebSphere Portal v6

State Handling in WebSphere Portal
Concepts APIs

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Screenshots: Bookmarkability
Note that not only the portal page but also the state of the portlets is restored.

WebSphere Portal v6

Screenshots: Back-Button Support

The back-button affects every navigational interaction with the pages or the portlets

WebSphere Portal v6

Key-Requirements for URL handling

Back- and Forward-Button Support The user can use the browsers back and forward buttons to switch between recent views Bookmarkability The current view can be saved into a client side bookmark The bookmark can be accessed at any time (probably requires a logon first) The bookmark must remain valid across portal versions Crawlability Web-Crawlers (e.g. Googlebot) can crawl portal pages and index them Cacheability Views of pages must be cacheable Non-Functional Requirements Respect URL size limitations (2KB) as imposed by RFC 1738 Performance during URL generation

WebSphere Portal v6

Key-Concept: Navigational State

The client requests a view of the portal content by sending a URL The server constructs the view based on
State in the URL (navigational state) State in the session (more general, based on cookies) State in the persistence layer (DB)


Portal Server
session state session

navigational state

persistent state

Back-button, bookmarks, crawlers, caches only affect the URL the view is identified by state in the URL the content is provided by long term persistent information (i.e. session and/or DB, LDAP)
View of the Content Content

WebSphere Portal v6

Navigational State
Navigational state is all information required to define the view of portal content Navigational state is encoded into the URL The URL is the only place to store navigational state in all URLs need to contain the complete navigational state The navigational state is the aggregation of
State managed by WebSphere Portal State managed by different portlet windows (JSR168 and JSR286)

Navigational State contains ...

Page selection Label selections Expansion states of navigation Theme-Template ... Render Parameters of all visited portlets

This is a lot of information that cannot be handled by the application independently State handling API

Different Navigational State results in different URLs.

(but the same Navigational State does not neccessarily result in the same URLs)

WebSphere Portal v6

Navigational State Processing

During request processing the URL is decoded into a navigational statedocument

Request Start URL Decode URL S1 PreProcess NavState S2 Handle Request Can be customized via Eclipse extension points (upcoming release)

This state-document can be modified during a PreProcessing phase

Extensible via Eclipse-extension points

PreProcessing can be used to apply special business logic, e.g.

reset portlet state or render parameters on page changes select pages based on URL parameters etc. ...

WebSphere Portal v6

Navigational State and Crawlability

How crawlers work Crawlers fetch pages via GET requests They follow each link that is reachable via GET (idempotent operation) If such links point to different URLs they get indexed individually What site-owners typically expect Every portal page is indexed, but only once Effect with Navigational State Every navigational state combination is indexed As a result a portal page is indexed multiple times, once for every different view

The same portal page in different navigational states different URLs

WebSphere Portal v6

Navigational State and Crawlability (contd)

Goal Per default, only the initial view of a page is indexed by a crawler Customers can override this behaviour and Solution WebSphere Portal detects if a crawler requests a page or a browser For crawlers the navigational state encoded with a URL is stripped to only contain the page selection State Normalization Trivia WebSphere Portal has additional crawler support
Site map References to the site map in every page (as a hidden link) Robot directives based on the cacheheaders

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Action Request

Render Request
Request Start

Two-Phase Processing Model

The Portal Programming Model distinguishes between two processing phases
This redirec Action Processing behaviour can be fine-tuned by a number of settings (see info-center)

Request Start



Modies server side state of resources redirect.action.without.session Is executed sequentially across all prohibit.implicit.redirect involved resources (e.g. Portlets) to avoid wps.multiple.action.execution side effects wps.enforce.redirect Since JSR286 the distribution of events is part of the redirect.commandphase action processing Results in new navigational state avoid.redirect.commands

S1 Action Handling S2 yes


Requests a view of the addressed resources without modifying them (idempotent operation) May be executed in parallel on the addressed resources (parallel portlet rendering)

S2 Rendering


Request End

Render- and Action-Phase do NOT neccessarily occur in the same request

WebSphere Portal v6

Action URLs
Actions and events are per design nonidempotent operations Their semantic correlates with the unsafe HTTP operations POST, PUT
Action SHOULD be represented by markup fragments that result in such HTTP requests, i.e. in FORMs

Examples: Performing a logon or a logout Creation of a new data record in the DB (e.g. after assembling data in a form) Deletion of a DB entry Adding an item to a shopping cart (session based) Counter Examples: Switching pages or views Execution of a query (e.g. a search query)

Actions can only be triggered by ActionURLs (i.e. URLs that are flagged specifically) For security reasons WebSphere Portal has two action-URL-security-mechanisms (next slides):
Dangerous Action-URL protection Multiple Action-URL protection

WebSphere Portal v6

Dangerous Action-URL Protection

Actions are potentially dangerous because they modify server side state
E.g. buy an item or delete a document

Malicious Mallory

Naive Alice

Goal: the user must be protected from unintentionally executing an action URL contains the command
by clicking a link in an E-Mail by invoking a bookmark ...
to transfer $1M to from Alicess to Mallorys account

Creates Action URL e-mail

Sends URL to Bob

Receives URL

Solution: Actions are only executed if the URL that triggers the action has been created in the active session
If the user has logged in a session is guaranteed to exist If the user did not log in, actions are unprotected but cannot do harm anyway Clicks URL
Rejected because the sessions dont match!

URL rejected!

Session 1

Session 2

WebSphere Portal v6

Multiple Action-URL protection

Action URLs are potentially dangerous If an action-URL is invoked multiple times unintentionally then this might lead to unexpected results
E.g. the purchase of more items than expected

Goal: the user should be protected from unintentionally invoking an action multiple times Solution: Action-URLs are assigned a unique ID WebSphere Portal keeps track of the actions-URL that have been invoked during a session and refuses to invoke the same action-URL twice Problems with this solution:
The solution assumes that most applications misbehave, i.e. not consistently use the HTTP verbs Well-behaving applications are restricted There exists a memory overhead in bookkeeping multiple-action protection can be disabled on a per-portlet basis

This can happen more-often than expected

many applications do not consistently represent actions as POST/PUT but sometimes as GET If represented as GET then the use of the back-button or bookmarks would cause multiple action execution

WebSphere Portal v6

Generation of Action-URLs
In Portlets Use the Portlet-API (JSR168, JSR286 or legacy)
javax.portlet.* <portlet:actionURL>

In Themes and Skins There should be no need to create portlet action URLs from themes or skins In exceptional cases use the statehandling API
<%@ taglib uri="" prefix="portlet" %> <form method="POST" action="<portlet:actionURL/>"> Enter Zip Code: <input type="text" name="zip" value=""> <input type="submit" name="submit" value="Search"> </form>

In exceptional cases use the statehandling API Action-URL in a portlet-JSP* portlet. PortletTargetAccessorController

WebSphere Portal v6

Always represent actions via the POST or PUT verb Enable redirect after the action processing phase Disable the multiple action-URL protection feature as a result all URLs in the back-button history or the addressbar (for bookmarking) will be safe render URLs

WebSphere Portal v6

Render URLs
Render URLs are used to represent idempotent operations
there should be no side-effects when invoking a render URL

Examples: Navigation to different pages or tabs within a portlet Search queries Expanding/collapsing a tree navigation widget ... Basically every interaction that requests a different view of a resource versus modifying the resource

Their semantic correlates with the safe HTTP operation GET Render-URLs are the key to back-button support, bookmarkability and crawlability of portal applications!

WebSphere Portal v6

URL examples
Navstate: sel=dogs Session: empty Navstate: sel=cart Session: 10 cats


Navstate: sel=cats Session: empty


WebSphere Portal v6

Generation of Render-URLs
In Portlets Use the Portlet-API (JSR168, JSR286 or legacy)
javax.portlet.* <portlet:renderURL>

In Themes There should be no need to create portlet action URLs from themes or skins In exceptional cases use the statehandling API

In exceptional cases use the statehandling API* portlet. PortletTargetAccessorController

Render-URL in a portlet-JSP

<%@ taglib uri="" prefix="portlet" %> <a href="<portlet:renderURL> <portlet:param name="tab" value="tab-2"/> </portlet:renderURL>"> 2nd Tab</a>

For common usecases there exists a easy-to-use convenience API url.PortalURLGenerationService <portlet-ext:portalRenderURL>

WebSphere Portal v6

When designing an application, consider that the same app can be viewed in different state instead of setting the app into a different UI state Represent the normalized set of information that identify the different views a navigational state (render parameters for JSR168 portlets) Encode changes in different views as render-URLs Reserve action-URLs for real state changes in the backend (session, DB) Portlets are strongly encouraged to use the Portlet-APIs to generate URLs, only use WebSphere Portal APIs for specific and special usecases

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Encoding (format) of URLs

URLs must contain
Portal instance identification Navigational state (i.e. the aggregation of the navigational state of WebSphere Portal and ALL of the targeted applications) Potentially Action Parameters

URL formats Rich URLs

Efficient encoding format that handles the general case. Not targeted for human deciphering

URL Mappings
Human readable but less functional

this is a lot of information!

Friendly URLs
Human readable

Piece-of-Content URIs
Late binding mechanism, allow to target content instead of portal artifacts

WebSphere Portal v6

Navigational State
Navigational state can be regarded as an (XML) document of stateinformation This information needs to be encoded into the URL
Efficiently wrt. CPU cycles and small URL lengths

Example State Document, 1521 Bytes

1521 Bytes vs 358 bytes Rich URL: 358 bytes only
/c1/lZDRaoMwFIafpQ8wckxidJepbsno7I watd6IF6Mos26sdJ1Pv4QyBhYtyyEXh4_v 55yDKmTq0JzafXNsh0PzhkpUsVqAAvIoMY DgDLCLSeIpxwEAw3eszjdOmscCO0DjB8MD iTV4AIr8yxZ0fbEJYwERAbP2HOXshk1v2I XddXl2y2HmcZj4frhdW_8eRzLC_hpPGQCnyxzu_0ip2iHKu_vuv5LQg13tQ59e1y MMlQCrdNufFadP2bdmBXmpyPJIeeKhdNH32tVpMcodNLDjDXM607k6N_c4aCfx_V Vc50Huc6R4khP8sENP_4lOyOm4ytHPpX9N 5rXUL71Mb9ydbeoB-InAFV

WebSphere Portal v6

Syntax of Rich-URLs
Codec Identifies the encoding algorithm and the version of the state document
Backwards compatibilty of URL formats

/!ut/p Identifier that denotes the start of the first codec (important for friendly URLs later on) The actual token value has historic reasons and can be reconfigured by the customer /ctx The portal context, e.g. /wps/portal

A URL may contain more than one codec (they override from left to right) Compressed-State A gzipped and base64 encoding of a binary XML serialization (non-standard, optimized for WebSphere Portal)

WebSphere Portal v6

Constant across all URLs generated during a request Problem to solve The serialization of a full state document is still relatively time consuming Needs to be done for EVERY URL on a page, potentially 100s Solution Assume that the state per URL only differs slightly from the state of the request Only encode this delta relative to the request state (via <base> tag) delta URLs are enabled per default relative URLs are disabled per default Differs per URL

Challenges with Delta URLs Introduces relative URLs and the use the <base> tag. Some ad-hoc Javascript does not work with this. Introduces URL aliases and therefore reduces cacheability of pages.

WebSphere Portal v6

The effect of Delta-URLs

Without Delta-URL
<a class="wpsNavItem wpsNavLevel1" href="/wps/myportal/!ut /p/c1/fc3LDoIwEIXhZ_EJ5 nSgLS7BS5sYCJWAyIawMIRE wIXxW2Xmuic5Z8vQx35LcNrGofn tC7DnVrqVG_gEB0tw9RVDJa yhpKaAe37VfXNSVRNaVggLg -7yzX0ICLPjRMqnzl6KydEAD oEv7996Hjx6X48smyILfcm5zTjKmwq7zjR5zi6k cN2_w0Bjn/" > PetStore </a>

With Delta-URL
<a class="wpsNavItem wpsNavLevel1" href="dl2/d1/L2dJQSEvUU t3QS9ZQnB3LzZfRzBRMDNGS DIwR1VTNDAyNTVVMDY1NzIw MDc!/" > PetStore </a>

Example: Navigation URLs

WebSphere Portal v6

Delta-Codecs: the <base> tag

Delta codecs add a /delta/state suffix to the current URL
the final URLs become longer and longer because the delta-suffixes add up


Delta-URL of the request

scheme://host:port/ctx/!ut/p/codec/stat e/delta/state1
apply the delta and compute the new state

Solution: Each page encodes the normalized state as the <base> tag in the header Delta-URLs are suffixes to this <base> tag, not the URL in the address bar Delta-Suffixes are limited to a maximum of one suffix Note: If custom code (e.g. JS code) follow links, the <base> tag must be respected!


Normalized State encoded into the base tag

<base href = scheme://host:port/ctx/!ut/p/codec/sta te1>

Relative URLs reference the base tag

<a href = delta/state2>

click on the relative URL

URL of next request

scheme://host:port/ctx/!ut/p/codec/stat e1/delta/state2

WebSphere Portal v6

Design your application such that it respects the <base> tag and can cope with relative URLs
a common mistake is to pass URLs as parameters to JS functions. Read the href attribute of anchor tags instead

Enable the generation of relative URLs in WebSphere portal Use render parameters often, but ...
... normalize the set of render parameters ... choose short parameter names (no need to make them human readable, use JAVA constants for readability)

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Virtual Portals and URLs

Virtual portals (VP) represent multiple logical portal that run inside the same portal instance The content of the VPs is separated from each other each VP is addressable separately via its own URL prefix VPs are uniquely identified via an ObjectID. This ID is however not suitable to be used as the address of the ID (because of readability reasons)

Hosting Portal Server

Default Portal


Shared DB
UR L 1

Virtual Portal 1


Virtual Portal 2

WebSphere Portal v6

Syntax of Virtual-Portal URLs

Hostname (upcoming) Different virtual portals can be addressed via different hostnames The HTTP server needs to listen to all hostnames to route the requests to the hosting portal (per default listens to *) WP determines the VP ID via a hostname-to-VP mapping table In case of proxy servers there exists a public plug-point to let the customer specify how to decode the hostname from the request (e.g. via header) VPName A path prefix contains a unique identifier (name) for a VP WP determines the VP ID via a name-toVP mapping table The assignment of a hostname and a prefix per VP is mutually exclusive Recommendation The assignment of a hostname to a VP matches the semantic of a VP better than the prefix mapping it should be preferred

All access points into WP use the same policy to address VPs, including the REST services.

WebSphere Portal v6

Virtual Portal URLs

The Virtual-Portal-Manager Portlet


WebSphere Portal v6

Generation of Virtual Portal URLs

It is not supported (via APIs) to link from one virtual portal into another virtual portal
VPs are independent, OIDs cannot be queried across VPs so there is no way to address artifacts Same behaviour as for inter-portal linking

All URL generation APIs will automatically consider the current VP and add hostname or VP-prefix accordingly
current = VP of the executing request

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

URL mappings allow to define human readable URL prefixes that lead to portal pages URL mappings can only be used as the entry point into WP, all subsequent URLs lose those prefixes
Because the mapping is not bijective


Content Nodes

shop shoes


The URL prefixes can form hierarchies The topology formed by URL mappings is however uncorrelated with either the navigation or content topology (see friendly URLs)

These hierarchies are independent!

/wps/portal/home /wps/portal/home/shop /wps/portal/home/shoes

WebSphere Portal v6

Syntax of URL-Mappings
Context-Label A path segment that can be chosen by the portal administrator The concatenation of all path segments forms the URL-Mapping



WebSphere Portal v6

Generation and Assignment of URL-Mappings

URL mappings can be managed via the admin UI, XMLAccess or Scripting URL mappings can be hardcoded into HTML markup or published outside of the portal markup There is no API to programmatically construct URL-Mapping URLs!

The URL-Mapping Portlet

WebSphere Portal v6

DOs Build a set of user-friendly URLs that can be published (e.g. in print media or bookmark collections) Maintain a stable set of URLs that will not change even if the portal site topology changes Use as hard-coded entry point URLs, e.g. to link across sites or virtual portals DONTs Try to keep the structure of the URL mapping hierarchy in sync with the page hierarchy (significant maintenance effort!) Consider the URL mappings as readable names for pages. These names will not be preserved during navigation.

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Friendly-URLs (upcoming)
Friendly-URLs result in human readable URL prefixes that lead to portal pages Each content node might have a friendly name assigned The friendly-URL is a hierarchical path constructed from these names based on the content topology (see URL mappings) Every URL that is generated by WP APIs will contain the friendly-path automatically
It is even guaranteed that every URL that leads to a particular page will start with the pages friendly-path info shoes

Content Nodes
root home shop

/wps/portal/home /wps/portal/home/shop /wps/portal/home/shop/shoes /wps/portal/home/shop/shoes/!ut/p/04_SB8K8xLLM9MS...

WebSphere Portal v6

Syntax of Friendly-URLs
Friendly-Name A path segment that is associated with a content node (page) The friendly-path is generated based on the content topology Suffix The navigational state is encoded as a suffix
Because the friendly path itself does not contain enough information to maintain the navigational state!


Trivia If a URL-mapping prefix collides with a friendly name the URL-mapping takes precedence Friendly-URLs are readable but potentially longer than rich-URLs

There exist APIs to produce URLs that contain the friendly-path only (used for entry-point URLs)

WebSphere Portal v6

Use friendly-URLs if ...
... your application requires to contain a human-readable identifier ... you use security proxies that peform access control based on URL prefix matching

Keep in mind that ...

... URLs become longer ... there is a performance impact in computing friendly URLs for page changes (because delta encoding is no longer possible)

WebSphere Portal v6

Generation and Assignment of Friendly-URLs

Friendly-names can be managed via the admin UI, XMLAccess or Scripting
In XMLAccess and Scripting they appear as page metadata

The Page-Properties Portlet

Friendly-paths are generated automatically without the need for special APIs To generate URLs that contain the friendly-path only
1. Pass keepNavState=false to the URL-tags 2. Use the ly.service.FriendlySelectionSe rvice API

WebSphere Portal v6

Different Types of URLs

Render-URLs and Action-URLs Rich-URLs and Delta-URLs Virtual-Portal URLs URL-Mappings Friendly-URLs Piece-of-Content URLs

WebSphere Portal v6

Intermezzo: URLs, URIs and Resources

So far WebSphere Portal URLs specify the exact location of resources
the navigational state specifies the exact portal page and the status of the UI widgets (portlets)

Uniform Resource Locator

Uniform Resource Identifier

The same content (document) e.g. might be located on different pages and is therefore addressable via different URLs For some usecases however it is desirable to address content independent of its location

The piece of content that is identified by a URI or located by a URL

Content ID != URL


portal (display)

Actual content (displayed)

WebSphere Portal v6

Piece-of-Content (POC) URIs

Content can be identified via a unique ID
it has a URI

POC Framework (WP 6.01) Provides mechanisms to find a view of a piece-of-content in a given portal context
converts from URI to URL

The URI that identifies the content is typically not the same as the URL that displays this content
there may be many URLs that display the same URI the URL can be used as the URI if there is only one possible content location

Allows custom code to define their own content schemes and participate in the view resolution

WebSphere Portal v6

POC-URI Resolution
Resolution out-of-context Client requests a view of a URI
Without portal context, e.g. by clicking an e-mail link

Resolution in-context Client clicks on a link that points to a URI during interaction with the portal
E.g. by clicking on a search result entry


POC servlet

POC resolver
find location


Portal servlet

POC resolver
find location

URI + navstate navstate

navstate (URL) URL


Portal servlet

Portal Rendering

Portal Rendering
navstate markup markup

navstate markup markup

WebSphere Portal v6

Syntax of POC-URLs
POC Servlet

Resolution servlet

Identification of the piece-of-content

Trivia The POC framework can also be used to directly access the content as a data stream (vs. its view, see documentation) The POC servlet is the well-defined entry point into the resolution framework There exist a protected and an unprotected servlet (poc vs. mypoc) The URI is passed as a QueryParameter
this syntax can be used with GET-FORMs Additional query parameters can be added (see documentation)

The POC servlet computes the navigational state that represents the view of the URI and redirects

WebSphere Portal v6

Generation of POC-URLs
POC-URLs can be generated via the e.PocService API Via a TAG API in the websphere/portal/v6.0.1/resolv er namespace

<%@ taglib uri=" /websphere/portal/v6.0.1/resolver" prefix="resolver" %>

Resolved-URL in a JSP

<form method="GET" action="<resolver:resolvedURL/>"> Enter POC-URI: <input type="text" name="uri" value=""> <input type="submit" name="submit" value=Display"> </form>

WebSphere Portal v6

Use POC-URLs if you want to link to content and not to explicit navigational state (e.g. search results, documents, etc.) POC-URLs can be encoded very efficiently, because the resolution process only happens when a link is clicked (late binding) Extend the POC framework by adding custom URI schemes

WebSphere Portal v6

Addendum: StateHandling and Client-Side-Aggregation

In the client-side aggregation the navigational state is managed inside the DOM Some interactions still require a server roundtrip the navigational state needs to be encoded as a URL URLs in server side generated markup need to be decoded by the client to update the navigational state There exists a public REST service that allows to encode and decode navigational state to and from URLs

WebSphere Portal v6

References 603_behl.html 612_behl.html p.ent.doc/wps/dgn_ptltld.html