Professional Documents
Culture Documents
What you always wanted to know about URIs in WebSphere Portal or more than that
Dr. Carsten Leue (cleue@de.ibm.com)
2007 IBM Corporation
The companies and people in this scenario are fictitious. Actual user interfaces may differ from those depicted here.
WebSphere Portal v6
WebSphere Portal v6
Agenda
State Handling in WebSphere Portal
Concepts APIs
WebSphere Portal v6
Screenshots: Bookmarkability
Note that not only the portal page but also the state of the portlets is restored.
WebSphere Portal v6
WebSphere Portal v6
WebSphere Portal v6
Client
Portal Server
session state session
navigational state
persistent state
DB
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)
This is a lot of information that cannot be handled by the application independently State handling API
WebSphere Portal v6
Request Start URL Decode URL S1 PreProcess NavState S2 Handle Request Can be customized via Eclipse extension points (upcoming release)
transform
WebSphere Portal v6
WebSphere Portal v6
WebSphere Portal v6
WebSphere Portal v6
Action Request
Render Request
Request Start
Request Start
Decoding
Decoding
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
Rendering
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
no
Request End
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
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
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
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
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="http://java.sun.com/portlet" 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>
WebSphere Portal v6
Recommendations
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
Render-URL
Action-URL
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
Render-URL in a portlet-JSP
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %> <a href="<portlet:renderURL> <portlet:param name="tab" value="tab-2"/> </portlet:renderURL>"> 2nd Tab</a>
WebSphere Portal v6
Recommendations
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
WebSphere Portal v6
URL Mappings
Human readable but less functional
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:
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
scheme://host:port/ctx/!ut/p(/codec/compressed-state)*
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
Delta-Codecs
scheme://host:port/ctx/!ut/p/codec/state/delta/state
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
With Delta-URL
<a class="wpsNavItem wpsNavLevel1" href="dl2/d1/L2dJQSEvUU t3QS9ZQnB3LzZfRzBRMDNGS DIwR1VTNDAyNTVVMDY1NzIw MDc!/" > PetStore </a>
WebSphere Portal v6
request
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!
equivalent
WebSphere Portal v6
Recommendations
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
WebSphere Portal v6
client
Shared DB
UR L 1
Virtual Portal 1
URL 2
UR L3
Virtual Portal 2
WebSphere Portal v6
All access points into WP use the same policy to address VPs, including the REST services.
WebSphere Portal v6
Examples
WebSphere Portal v6
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
WebSphere Portal v6
URL-Mappings
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
URL-Mappings
home
Content Nodes
shop shoes
info
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)
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
URL-Mapping
scheme://host:port/ctx/vpname(/context-label)*
WebSphere Portal v6
WebSphere Portal v6
Recommendations
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
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
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!
friendly-path
scheme://host:port/ctx/vpname(/frdly-name)*(/!ut/p/...)?
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
Recommendations
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
WebSphere Portal v6
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 com.ibm.portal.resolver.friend ly.service.FriendlySelectionSe rvice API
WebSphere Portal v6
WebSphere Portal v6
URL
Uniform Resource Locator
URI
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
URL
Resource
The piece of content that is identified by a URI or located by a URL
Content ID != URL
client
portal (display)
WebSphere Portal v6
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
client
URI
POC servlet
URI
POC resolver
find location
client
URL
Portal servlet
POC resolver
find location
URL
Portal servlet
Portal Rendering
Portal Rendering
navstate markup markup
WebSphere Portal v6
Syntax of POC-URLs
POC Servlet
Resolution servlet
scheme://host:port/[my]poc/vpname?uri=<URI>(&<k>=<v>)*
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 com.ibm.portal.resolver.servic e.PocService API Via a TAG API in the http://www.ibm.com/xmlns/prod/ websphere/portal/v6.0.1/resolv er namespace
<resolver:resolvedURL/>
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
Recommendations
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
WebSphere Portal v6
References
http://www.ibm.com/developerworks/websphere/library/techarticles/0603_behl/0 603_behl.html http://www.ibm.com/developerworks/websphere/library/techarticles/0612_behl/0 612_behl.html http://www.w3.org/TR/uri-clarification http://www.w3.org/TR/webarch/ http://www.w3.org/2001/tag/doc/whenToUseGet.html http://publib.boulder.ibm.com/infocenter/wpdoc/v6r0/index.jsp?topic=/com.ibm.w p.ent.doc/wps/dgn_ptltld.html http://www.ietf.org/rfc/rfc1738.txt