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.
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.
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 on an ActionURL will result in action parameters, not render parameters or public render parameters.
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.
An example of creating a portlet URI would be:
... PortletURL url = response.createRenderURL(); url.setParameter(“customer”,”foo.com”); url.setParameter(“show”,”summary”); writer.print(“<A HREF=\””); url.write(writer); writer.print(”\”>Summary</A>”); ...
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 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.
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(); url.setParameter(“paymentMethod”,”creditCardInProfile”); url.setWindowState(WindowState.MAXIMIZED); writer.print(“<FORM METHOD=\”POST\” ACTION=\””); url.write(writer); writer.print(”\”>”); ...
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.
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.
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.
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.
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.