javax.portlet
Interface PortletURL

public interface PortletURL

The PortletURL interface represents a URL that reference the portlet itself.

A URL is created through the RenderResponse and additional parameters can be added to this URL. The complete URL can be converted to a String which is ready for embedding into markup.

There are two types of PortletURLs:

• render URLs created with RenderResponse.createRenderURL as optimzed action, only setting the render parameters
• action URLs created with RenderResponse.createActionURL for triggering an action request

A portlet URL does not need to be a valid URL when converted to a String. It may contain special tokens that will be converted to a URL by the portal.

Method Summary

void	addParameter(java.lang.String name, java.lang.String value) Adds the given String parameter to this URL.
void	addParameter(java.lang.String name, java.lang.String[] values) Adds the given String array parameter to this URL.
void	setParameters(java.util.Map parameters) Sets a parameter map for this URL.
void	setPortletMode(PortletMode portletMode) Indicates the portlet mode the portlet must be in, if this portlet URL triggers a request.
void	setSecure(boolean secure) Indicated the security setting for this URL.
void	setWindowState(WindowState windowState) Indicates the window state the portlet should be in, if this portlet URL triggers a request.
java.lang.String	toString() Returns the complete URL as a string.

Method Detail

setWindowState

public void setWindowState(WindowState windowState)
                    throws WindowStateException

Indicates the window state the portlet should be in, if this portlet URL triggers a request.

A URL can not have more than one window state attached to it. If more than one window state is set only the last one set is attached to the URL.

Parameters:

windowState - the portlet window state

Throws:

WindowStateException - if the portlet cannot switch to this state, because the portal does not support this state, the portlet has not declared in its deployment descriptor that it supports this state, or the current user is not allowed to switch to this state. To avoid this exception the portlet can check the allowed window states with Request.isWindowStateAllowed().

setPortletMode

public void setPortletMode(PortletMode portletMode)
                    throws PortletModeException

Indicates the portlet mode the portlet must be in, if this portlet URL triggers a request.

A URL can not have more than one portlet mode attached to it. If more than one portlet mode is set only the last one set is attached to the URL.

Parameters:

portletMode - the portlet mode

Throws:

PortletModeException - if the portlet cannot switch to this mode, because the portal does not support this mode, the portlet has not declared in its deployment descriptor that it supports this mode for the current markup, or the current user is not allowed to switch to this mode To avoid this exception the portlet can check the allowed portlet modes with Request.isPortletModeAllowed().

addParameter

public void addParameter(java.lang.String name,
                         java.lang.String value)

Adds the given String parameter to this URL.

This method does not url encode parameters. Parameters that need url encoding must be "x-www-form-urlencoded" before using the addParameter method, e.g. by using the java.net.URLEncoder.encode method.

A portlet container may prefix the attribute names internally in order to preserve a unique namespace for the portlet.

Parameters:

name - the parameter name

value - the parameter value

Throws:

java.lang.IllegalArgumentException - if name or value is null.

addParameter

public void addParameter(java.lang.String name,
                         java.lang.String[] values)

Adds the given String array parameter to this URL.

This method does not url encode parameters. Parameters that need url encoding must be "x-www-form-urlencoded" before using the addParameter method, e.g. by using the java.net.URLEncoder.encode method.

A portlet container may prefix the attribute names internally in order to preserve a unique namespace for the portlet.

Parameters:

name - the parameter name

values - the parameter values

Throws:

java.lang.IllegalArgumentException - if name or values is null.

setParameters

public void setParameters(java.util.Map parameters)

Sets a parameter map for this URL.

All previously set parameters are cleared.

A portlet container may prefix the attribute names internally, in order to preserve a unique namespace for the portlet.

Parameters:

parameters - Map containing parameter names for the render phase as keys and parameter values as map values. The keys in the parameter map must be of type String. The values in the parameter map must be of type String array (String[]).

Throws:

java.lang.IllegalArgumentException - if parameters is null.

setSecure

public void setSecure(boolean secure)
               throws PortletSecurityException

Indicated the security setting for this URL.

Secure set to true indicates that the portlet requests a secure connection between the client and the portlet window for this URL. Secure set to false indicates that the portlet does not need a secure connection for this URL. If the security is not set for a URL, it will stay the same as the current request.

NOTE: using this URL may result in loosing the current session, depending on the session implementation.

Parameters:

secure - true, if portlet requests to have a secure connection between its portlet window and the client; false, if the portlet does not require a secure connection.

Throws:

PortletSecurityException - if the run-time environment does not support the indicated setting

toString

public java.lang.String toString()

Returns the complete URL as a string. The string is ready to be embedded in markup.

Overrides:

toString in class java.lang.Object

Returns:

the encoded URL as a string