Portal 6.0 Advanced URL Generation Helper classes

Technote (troubleshooting)


This document contains the IBM WebSphere Portal 6.0 Advanced URL Generation Helper classes that make it easy to create URLs using the Advanced URL Generation SPI.

Resolving the problem

In WebSphere Portal V6.0 and later, the Advanced URL Generation APIs are available. These require several different calls to various parts of the API to create the URLs for inclusion in either the .jsp's of your portlets, your portal code directly, your servlets, or your LoginUserAuth class.
To help you rapidly develop new code, we have created the following Helper classes to cover approximately 80% of the business needs of our customers.

Three important notes:

  • The uniquename for the portlet can only be set through XMLAccess (the XML Configuration Interface).
  • When the class refers to PortletWindow, it is in regard to the component that holds the portlet instance on the page..
  • When creating links across virtual portals, there is only one specific way to do this which uses the stateless package. Instead of the MyServerContext, you must pass in the MyVPServerContext and use that to generate the URL to the page you want. No other way is supported. More information is contained below.

More information can be found in Document #21322423, " How go create a link to a portlet", which also describes how to set the unique name on the page. While this document references 5.1, the behavior is very similar in 6.0.

NOTE: If you downloaded this originally, note that this is an brand new set of files. Many of the methods are the same but the information has been updated to clarify issues and add some new functionality. This new package also includes JavaDoc to better understand the code.

Stateless package
The first class provided is the OfflineURLHelper. This class is used to create URLs when you do not have access to the request or response objects, or when you do not want the URL to rely on the state that is in those current objects. This class is best used within the LoginUserAuth class when you want to redirect the login to specific pages. The signature for this method is as follows:
    public static String generateUrl(
        String pageName, String portletName,
        HashMap params,
        MyServerContext serverContext,
        boolean nonPublicPage)
    throws StateException, NamingException, IOException {

  • The first string is the uniqueName of the page you are targeting.
  • The portletName is the uniqueName of the target portlet window. This setting can be Null.
  • The HashMap is a map of parameters to be passed to the target portlet. This can be null and is ignored if the portletName is Null.
  • The serverContext is based upon the proved class, MyServerContext, which you instantiate with the host name and port in use.
  • You must pass the boolean to indicate if you want the link to be created to a public page or a non-public page.

You can call this class as follows:
    MyServerContext serverContext = new MyServerContext(renderRequest.getServerName(),
      HashMap map = new HashMap();
      String[] value1 = {"testthis"};
      map.put("mysearchparam", value1);
      String targetURLStr = OfflineURLHelper.generateUrl(
      "page.uniquename","portletwindow.uniquename", map,
    serverContext, true);

The class, MyServerContext, is also included. It tells the StateService how to create the URL, specifically as to what host name and port to use and what the context paths are. (If you changed your values in your Portal environment, you must update these in the code provided.)

There is a subclass to this class, MyVPServerContext, that you would use when creating links across virtual portals. More information is provided in Document #1271209, "  Creating a link from a servlet to a page in a virtual Portal".

Servlet Request package
This Helper can be used to create links in your servlets and in your .jsp's, to create links to other pages, and create links to portlets within Portal. The first Helper is the ServletURLHelper which is used within servlets to target specific pages and portlets. If you want to make requests between IBM API portlets or JSR to IBM, you must use this package. There are two main overloaded methods.
    public static String generateUrl(
        throws StateException, NamingException, IOException {

    public static String generateUrlToPortlet(
        throws StateException, NamingException, IOException {

As with the method above, pageName, portletName, and parameters have not changed. The request and response object are required to be passed in so that Portal knows how to build the link.

This class can be called as follows:

    HashMap map = new HashMap();
    String[] value1 = {"testthisONE"};
      map.put("thisparam", value1);
      String targetURLStr = ServletURLHelper.generateUrl(
      "pageUnniqueName","portletWindowUniqueName", map, request, response);

As before, the portlet name can be Null, along with the map. For more detail on the methods, please refer to the included JavaDoc.

NOTE 1: Parameters passed to JSR 168 parameters for the action phase are not replicated to the render phase unless, in the action phase of your portlet, you specifically state to save those parameters.

NOTE 2: Be aware that if you are logged in as an administrator and you click a link that targets the edit mode, you can encounter an issue in which you will receive a "You are not authorized" message. This error can occur with legacy portlets that only now support Edit Shared Settings and configure but do not have the personalize mode for the administrative user.

Also in the ServletURLHelper is a method to get the current pageID.

The other Helper is the ThemeURLHelper. It contains several methods that can be useful in your theme coding such as methods to generate login URLs, logout URLs, or disposable URLs for images in the theme. There is one final method in the Helper for generating URLs with expansion state that can be used to create an expansion URL to select and expand a page and child pages at the same time. This allows you to create links in your portal so that when you click the page, all children display at the same time.

The main method is used to generate a URL to a page calling the portlet in solo. This method is mainly used when adding flyouts via theme extensions. To help support when using flyouts, you do not want the theme rendered. This method also adds the theme template of plain so that no theme is rendered. You can also use this method to generate links to pages with no theme displayed.
    public static EngineURL generateUrlForFlyout(
      String pageName, String portletName,
      HttpServletRequest request,
      HttpServletResponse response)
    throws StateException, NamingException, IOException {
Portlet Request Helper
This Helper class is used in portlet .jsp's and was changed for 6.0 so that it can take advantage of the now public PortletStateManager service. This Helper contains some of the same type of methods as the ServletURLHelper. The one addition is a boolean for telling the Portal StateManager to keep or drop the state. This is only for making URLs between standard API portlets.

The first method has the following signature. This is similar to the method, generateUrlStringWithStateInServlet, except that you will be passing in a portlet request and portlet response.
    public static String generateUrlString(
      String pageName, String portletName,
      HashMap params,
      boolean saveState,
      PortletRequest request,
      PortletResponse response)
    throws StateException, NamingException, IOException {
The boolean functions as the parameter does for the URLNavigational tag, keepNavigtionalState.
  • If set to False, the current navigational state (including all portlet modes, states, and render parameters) is not included in the URL and the portal is reset to its default state. If set to True, navigational state is included.

These methods are all called as follows:
    HashMap map = new HashMap();
    String[] value1 = {"showSearch"};
    map.put("requiredAction", value1);
      String targetURLStr = PortletURLGenerator.generateUrlStringInPortlet("pageuniquename","portletwindowuniquename", true, map, renderRequest, renderResponse);

This method is overloaded various times depending on what you want to do. Refer to the included JavaDoc for more information. You can target a specific mode, action phase, action, and a mode,

NOTE: Be aware that if you are logged in as an administrator and you click a link that targets the edit mode, you can encounter an issue in which you receive a "You are not authorized" message. This error can occur with legacy portlets that only now support Edit Shared Settings and configure but do not have the personalize mode for the administrative user.

This can be called as follows:
    HashMap map = new HashMap();
      String[] value1 = {"showSearch4"};
      map.put("requiredAction", value1)
      String targetURLStr = PortletURLGenerator.generateUrl("pageUniqueName", "portletWindowUniqueName", map, true, renderRequest, renderResponse, "edit");
    %> <a href="<%=targetURLStr%>">link to edit mode</a> <%

There are also methods to get the current PortletWindowID as well as the portletID.

Valid only for 6.0.1 and later releases:
The following two methods are usefull for Ajax:
    generateSinglePortletRenderURL(HashMap, String, WindowState, PortletRequest, PortletResponse)

    generateSinglePortletActionURL(HashMap, String, WindowState, PortletRequest, PortletResponse)

These methods allow you to use the SinglePortletRefresh action introduced via the DeveloperWorks article. With them, you can create URLs to portlets that do not include either skin or theme elements and is just the HTML markup returned by the portlet and/or the JSP.

Modifying the code
The wp.l2.url.Helper.jar file is provided below in case you want to modify this code to do something beyond the current functionality. You can import this as a .jar file into Rational Application Developer 7.0. Then add the WebSphere Portal v6.0 JRE and the WebSphere Portal v6.0 runtime libraries to the project.

You can use this as a web library for your portlets or other projects and call the methods statically. The service lookup is cached so that the response time for creating the links is improved.

Disclaimer: The code below in the Attachment section is sample code created by IBM. This sample code is provided to you solely for the purpose of assisting you in the development of your applications. The code is provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample code, even if they have been advised of the possibility of such damages.


This code is provided "AS-IS" with no warranty

Rate this page:

(0 users)Average rating

Add comments

Document information

More support for:

WebSphere Portal End of Support Products
WebSphere Portal

Software version:


Operating system(s):

AIX, HP-UX, Linux, Solaris, Windows, i5/OS, z/OS

Software edition:

Enable, Express, Extend, Server

Reference #:


Modified date:


Translate my page

Machine Translation

Content navigation