Portal 6.1 and 7.0 Advanced URL Generation Helper classes

Technote (FAQ)


Question

The IBM WebSphere Portal Advanced URL Generation Helper files make it easy to create URLs using the Advanced URL Generation SPI.

Answer

With IBM® WebSphere® Portal version 6.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 portlet 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 that, and that 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 below on this

More information can be found in Document# 1322423, " How to create a link to a portlet", which also describes how to set the unique name on the page.


NOTE: in 7.0 when operating in CSA mode, the navigation model is NOT supported and all portlets must act as if being rendered via wsrp. The helper has been updated to take this into account and will use the PortletPocService to create a url to a page. If you want to pass parameters or target an action you have to use public render parameters, or use events respectively.

NOTE: If you downloaded this file originally, be aware that this is a new set of files. Many of the methods are the same but the file has been updated to clarify some issues and add some new functionality. Additionally this package is backward compatible with the 6.1 helper files so no code change is necessary, but those methods are deprecated. This new set of helpers includes a factory design to allow you to request the helper you want and based upon the version of portal you are on, will return the correct implementation.

Factory package
This package contains the new factory class for getting the helper classes that you want. You can call this factory statically and it will retrieve the correct implementation class for you. There are 4 methods here for the use of the entire helper classes.

public static GenericPortletURLHelper getPortletURLHelper(
PortletRequest request,
PortletResponse response)
throws ServiceUnavailable {

public static GenericServletURLHelper getServletURLHelper(
String version)
throws ServiceUnavailable {

public static GenericThemeURLHelper getThemeURLHelper(
String version)
throws ServiceUnavailable{

public static GenericOffLineURLHelper getOffLineURLHelper(
String version)
throws ServiceUnavailable{

These methods are pretty straight forward and just return the correct implementation class. The other two classes in this package are the new exception thrown when a helper cannot be initialized and the constants for the version of portal you are on, The version of portal can be gathered from the PortletRequest through the PortalContext.

Stateless package
The first class provided is the GenericOfflineURLHelper interface. 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 created 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 or in servletFilters. 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 {

Definitions:
  • 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 on the proved class, MyServerContext, which you instantiate with the host name and port in use.
  • Finally, there is a boolean that you must pass 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(), renderRequest.getServerPort()+"");
GenericOffLineHelper offLineHelper = UrlHelperFactory.getOffLineURLHelper(FactoryConstants. versionyouwant);
HashMap map = new HashMap();
String[] value1 = {"testthis"};
map.put("mysearchparam", value1);
String targetURLStr = offLineHelper.generateUrl("page.uniquename","portletwindow.uniquename", map, serverContext, true);

The Class MyServerContext is also included. It tells the StateService how to create the URL, specifically what host name and port to use and what the context paths are. If you changed 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 file can be used to create links in your servlets and in your .jsp's to create links to other pages and portlets within Portal. The first Helper is the GenericServletURLHelper 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 {

and

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

As with the method above, pageName, portletName, and the 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:

GenericServletHelper servletHelper = UrlHelperFactory.getServletURLHelper(FactoryConstants. versionyouwant);
HashMap map = new HashMap();
String[] value1 = {"testthisONE"};
map.put("thisparam", value1);
String targetURLStr = servletHelper.generateUrl("pageUnniqueName","portletWindowUniqueName", map, request, response);

As before, the portlet name can be Null, along with the map. For more detail on the methods, 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 edit mode, you can run into an issue where you will get a "You are not Authorized" message. This error can happen 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 GenericServletURLHelper is a method to get the current pageID.

The Other Helper is the GenericThemeURLHelper. It contains several methods that can be very useful in your theme coding. It contains methods to generate login URLs, logout URLs, disposable URLs, as an example, for images in the theme. There is one final method in the Helper for generating URLs with expansion state. This can be used to create an expansion URL to select and expand a page and child pages at the same time. This will allow you to create links in your Portal that show all the children at the same time when you click on the page.

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 this, 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 GenericServletURLHelper. 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 very similar to the method, generateUrlStringWithStateInServlet, except 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 the same way as the parameter 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:

GenericPortletHelper portletHelper = UrlHelperFactory.getPortletURLHelper(portletRequest, portletResponse);
HashMap map = new HashMap();
String[] value1 = {"showSearch"};
map.put("requiredAction", value1);
String targetURLStr = portletHelper.generateUrl("pageuniquename","portletwindowuniquename", true, map, renderRequest, renderResponse);

This method is overloaded at 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 run into an issue in which you receive a "You are not Authorized" message. This error can happen 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:

GenericPortletHelper portletHelper = UrlHelperFactory.getPortletURLHelper(portletRequest, portletResponse);
HashMap map = new HashMap();
String[] value1 = {"showSearch4"};
map.put("requiredAction", value1)
String targetURLStr = portletHelper.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.

New changes for 6.1:
The inclusion of a Helper method to send shared parameters to a page: generateUrlPublicParams

This method is designed to work with JSR 286 and share the parameters with all portlets that are listening for those parameters.



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.5. Then you must add the WebSphere Portal JRE and the WebSphere Portal runtime libraries to the project. If you are using the stub directory you will also need to add the model controller jar to the build path.

Screen capture of new library in Rational Application Developer:




You can then uses 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 OF WARRANTIES:

The following enclosed code is sample code created by IBM Corporation. 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.


wp.l2.urlhelper.jar


Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

WebSphere Portal
Application Development

Software version:

6.1, 7.0

Operating system(s):

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

Software edition:

Enable, Express, Extend, Hypervisor Edition, Server

Reference #:

1461911

Modified date:

2011-04-28

Translate my page

Machine Translation

Content navigation