Skip to main content
Last updated August 29, 2013 06:56, by Martin Scott Nicklous

Portlet URLs

As part of its content, a portlet may need to create URLs that reference the portlet itself. For example, when a user acts on a URL that references a portlet (i.e., by clicking a link or submitting a form) the result is a new client request to the portal targeted to the portlet. Those URLs are called portlet URLs.

Portlet URLs

The Portlet API defines the PortletURL and ResourceURL interface. Portlets must create portlet URLs either using PortletURL or the ResourceURL objects. A portlet creates PortletURL/ResourceURL objects invoking the createActionURL, createRenderURL or the createResourceURL methods of the StateAwareResponse interface. The createActionURL method creates action URLs. The createRenderURL method creates render URLs. The createResourceURL method creates resource URLs. A render URL is an optimization for a special type of action URLs. The portal/portlet-container must not invoke the processAction method of the targeted portlet of a render URL.i The portal/portlet-container must ensure that all the parameters set when constructing the render URL become render parameters of the subsequent render requests for the portlet.

Render URLs should not be used for tasks that are not idempotent, i.e. that change state, from the portlet perspective. Error conditions, cache expirations and changes of external data may affect the content generated by a portlet as result of a request triggered by a render URL. Render URLs should be accessed via HTTP method GET as they should not change any state on the server. As a consequence, render URLs may become bookmarkable.

Note that Render URLs used within forms may not work on all portal/portlet-containers as the portal/portlet-container may ignore form parameters.

A resource URL allows the portlet serving resources with access to information of the portlet request. When rendering resources the portlet has full control over the output stream and can render binary markup.

Note that portlet URLs are only valid within the current request and need to be either written to the output stream in order to allow re-writing the portlet URL token into a real URL.

BaseURL Interface

The BaseURL interface provides the basic methods that are common for all URLs pointing back to the portlet, like ResourceURLs, ActionURLs, and RenderURLs. BaseURLs are always created either as a resource URL, action URL, or render URL.

Portlets can add application specific parameters to the BaseURL objects using the setParameter and setParameters methods. A call to any of the setParameter methods must replace any parameter with the same name previously set.iii All the parameters a portlet adds to a BaseURL object must be made available to the portlet as request parameters.iv Portlet developers should note that the parameters of the current render request are not carried over when creating an ActionURL or RenderURL. When creating a ResourceURL the current render parameters are automatically added to that URL by the portlet container, but are hidden to the getParameter calls of the portlet URL object. Setting parameters that are not public render parameters on an ActionURL will result in action parameters, not render parameters or public render parameters. If a public render parameter value is set or removed on an action URL, then the public render parameter will be set to the new value or removed when the URL is activated.

The portlet-container must “x-www-form-urlencoded” encode parameter names and values added to a BaseURL object.

If portlet developers namespace parameter names or values before adding them to a BaseURL object they are also responsible for removing the namespace. The portlet container will not remove any namespacing the portlet has done on these parameters..

If a portal/portlet-container encodes additional information as parameters, it must namespace them properly to avoid collisions with the parameters set and used by the portlet.

Using the toString method, a portlet can obtain the string representation of the BaseURL. Using the write(Appendable) method, the URL can be added to an appendable object such as a StringBuilder. If the portlet wants to include a portlet URL in the portlet content it should use the write(Writer) method to avoid potential overhead associated with string processing methods.

An example of creating a portlet URI would be:

 PortletURL url = response.createRenderURL();
 writer.print(“<A HREF=\””);

Portlet developers should be aware that the string representation of a PortletURL or ResourceURL may not be a well formed URL but a special token at the time the portlet is generating its content. Portal servers often use a technique called URL rewriting that post-processes the content resolving tokens into real URLs. It may even be an ECMA script method that may generate the URL at the time the user clicks on the link.

URL Properties

Properties can be used by portlets to set vendor specific information on the PortletURL object and thus use extended URL capabilities.

A portlet can set properties using the following methods of the BaseURL interface:



The setProperty method sets a property with a given name and value. A previous property is replaced by the new property. Where a set of property values exist for the name, the values are cleared and replaced with the new value. The addProperty method adds a property value to the set with a given name. If there are no property values already associated with the name, a new set is created.

Including a Portlet Mode or a Window State

A portlet URL can include a specific portlet mode (see PLT.8 Portlet Modes Chapter) or window state (see PLT.9 Window States Chapter). The PortletURL interface has the setWindowState and setPortletMode methods for setting the portlet mode and window state in the portlet URL. For example:

 PortletURL url = response.createActionURL();
 writer.print(“<FORM METHOD=\”POST\” ACTION=\””);

A portlet cannot create a portlet URL using a portlet mode that is not defined as supported by the portlet or that the user it is not allowed to use. The setPortletMode methods must throw a PortletModeException in that situation.vii. The change of portlet mode must be effective for the request triggered by the portlet URL.viii There are some exceptional circumstances, such as changes in access control privileges that could prevent the portlet mode change from happening. If the portlet mode is not set for a URL, it must have the portlet mode of the current request as defaultix.

A portlet cannot create a portlet URL using a window state that is not supported by the portlet container. The setWindowState method must throw a WindowStateException if that is the case.x The change of window state should be effective for the request triggered by the portlet URL. The portlet should not assume that the request triggered by the portlet URL will be in the window state set as the portal/portlet-container could override the window state because of implementation dependencies between portlet modes and window states. If the window state is not set for a URL, it must have the window state of the current request as defaultxi.

Portlet URL security

The setSecure method of the PortletURL interface allows a portlet to indicate if the portlet URL has to be a secure URL or not (i.e. HTTPS or HTTP). If the setSecure method is not used, the portlet URL should be of the same security level of the current request. If setSecure is called with true, the transport for the request triggered with this URL must be secure (i.e. HTTPS). xii If set to false the portlet indicates that it does not require a secure connection for the request triggered with such a URL.


The setAuthentication method allows a portlet to indicated if accessing the URL will require authentication. If this method is not used, or if authentication is set to false using this method, authentication will be allowed, but not required. The getAuthentication method allows the current authentication setting to be retrieved.

Fragment Identifier

The fragment identifier consists of additional information appended to the URL after a '#' character. A URL can have only a single fragment identifier. The fragment identifier must be formed according to rfc3986 "Uniform Resource Identifier (URI): Generic Syntax". The fragment identifier is often used to address a named anchor such as <a name="#fragmentIdentifier">, but it can also be used for other purposes such as to provide additional information for JavaScript routines on the client. If the fragment identifier is not specified by the portlet, the portal implementation can optionally append a fragment identifier to the URL. The setFragmentIdentifier method allows a fragment identifier to be appended to a URL. The fragment identifier appended with this method will not be namespaced. The portlet is responsible for performing any required namespacing. However, the fragment identifier string will be escaped as necessary. Setting the fragment identifier to null will remove a fragment identifier that was previously set using this method. Setting the fragment identifier to the empty string will create an empty fragment identifier. The getFragmentIdentifier method retrieves a fragment identifier previously set through setfragmentIdentifier. The portlet can permit or suppress generation of a fragment identifier using the setFragmentIdentifierPermitted method. If the fragment identifier is permitted, a fragment identifier set by the portlet will be appended to the URL. If the portlet does not set a fragment identifier, the portal implementation may append a fragment identifier to the URL. If the fragment identifier is suppressed, no fragment identifier at all will be appended to the URL. The portlet can use the isFragmentIdentifierPermitted method to determine whether the fragment identifier is permitted on the URL.

Portlet URL listeners

Portlets can register portlet URL listeners in order to filter URLs before they get generated either as a string via the toString method or written to the output stream via the write method of the BaseURL interface. The portlet URL listener is also called for a render URL that is added to a redirect URL via the method sendRedirect(location, renderUrlParamName).

For example the portlet could use URL listeners to set the caching level of resource URLs in one central piece of code (see PLT13.7).

In order to receive a callback from the portlet container before a portlet URL is generated the listener class needs to implement the PortletURLGenerationListener interface and register it in the deployment descriptor.

PortletURLGenerationListener Interface

The PortletURLGenerationListener interface provides callbacks for each portlet URL type. If the portlet application has specified one or more PortletURLGenerationListener

classes in the portlet deployment descriptor the portlet container must call

the method filterActionURL method for all action URLs before executing the write or toString method of these action URLsxiii

the method filterRenderURL method for all render URLs before executing the write or toString method of these render URLsxiv

the method filterResourceURL method for all resource URLs before executing the write or toString method of these resource URLsxv

The portlet container must provide the PortletURL or ResourceURL to generate to the filter methods and execute the write or toString method on the updated PortletURL or ResourceURL that is the outcome of the filter method call.

Registering Portlet URL Listeners

Portlet applications must register Portlet URL listeners in the portlet deployment descriptor under the application section with the listener element and provide the class name that implements the PortletURLGenerationListener as value in the listener-class element.

If more than one listener is registered the portlet container must chain the listeners in the order of how they appear in the deployment descriptor.

Please Confirm