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
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
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.
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.
<span id="PORTLETSPEC3-32" style="background-color: #fd4;">Setting parameters <span style="background-color: #8f8;">that are not public render
parameters </span> on an ActionURL will result in action parameters, not render
parameters<span style="background-color: #f88; text-decoration: line-through;"> or public render parameters</span>. <span style="background-color: #8f8;">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
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
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.
<div id="PORTLETSPEC3-21" style="background-color: #fd4;">
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
An example of creating a portlet URI would be:
PortletURL url = response.createRenderURL();
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.
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
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.
<div id="PORTLETSPEC3-13" style="background-color: #8f8;">
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
The getAuthentication method allows the current authentication setting to be
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
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
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
The PortletURLGenerationListener interface provides callbacks for each portlet
URL type. If the portlet application has specified one or more
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.