javax.portlet

Interface PortletURL

public interface PortletURL

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

A PortletURL is created through the RenderResponse. Parameters, a portlet mode, a window state and a security level can be added to PortletURL objects. The PortletURL must be converted to a String in order to embed it into the markup generated by the portlet.

There are two types of PortletURLs:

The string reprensentation of a PortletURL does not need to be a valid URL at the time the portlet is generating its content. It may contain special tokens that will be converted to a valid URL, by the portal, before the content is returned to the client.

Method Summary
voidsetParameter(String name, String value)
Sets the given String parameter to this URL.
voidsetParameter(String name, String[] values)
Sets the given String array parameter to this URL.
voidsetParameters(Map parameters)
Sets a parameter map for this URL.
voidsetPortletMode(PortletMode portletMode)
Indicates the portlet mode the portlet must be in, if this portlet URL triggers a request.
voidsetSecure(boolean secure)
Indicated the security setting for this URL.
voidsetWindowState(WindowState windowState)
Indicates the window state the portlet should be in, if this portlet URL triggers a request.
StringtoString()
Returns the portlet URL string representation to be embedded in the markup.
Note that the returned String may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

Method Detail

setParameter

public void setParameter(String name, String value)
Sets the given String parameter to this URL.

This method replaces all parameters with the given key.

The PortletURL implementation 'x-www-form-urlencoded' encodes all parameter names and values. Developers should not encode them.

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 are null.

setParameter

public void setParameter(String name, String[] values)
Sets the given String array parameter to this URL.

This method replaces all parameters with the given key.

The PortletURL implementation 'x-www-form-urlencoded' encodes all parameter names and values. Developers should not encode them.

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 are null.

setParameters

public void setParameters(Map parameters)
Sets a parameter map for this URL.

All previously set parameters are cleared.

The PortletURL implementation 'x-www-form-urlencoded' encodes all parameter names and values. Developers should not encode them.

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, if any of the key/values in the Map are null, if any of the keys is not a String, or if any of the values is not a String array.

setPortletMode

public void setPortletMode(PortletMode portletMode)
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. The PortletRequest.isPortletModeAllowed() method can be used to check if the portlet can set a given portlet mode.

See Also: PortletRequest

setSecure

public void setSecure(boolean secure)
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.

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

setWindowState

public void setWindowState(WindowState windowState)
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. The PortletRequest.isWindowStateAllowed() method can be used to check if the portlet can set a given window state.

See Also: PortletRequest

toString

public String toString()
Returns the portlet URL string representation to be embedded in the markup.
Note that the returned String may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

Returns: the encoded URL as a string