Java Portlet API V3.0 3.0.1 · javax.portlet.BaseURL

Modifier and Type	Method and Description
public void	addProperty(String the key of the property key, String the value of the property value) Adds a String property to an existing key on the URL.
public Appendable	Returns: Appendable the Appendable object containing the URL append(Appendable the object to receive the URL out) Appends the portlet URL to the appendable object.
public Appendable	Returns: Appendable the Appendable object containing the URL append(Appendable the object to receive the URL out, boolean escapeXML) Appends the portlet URL to the appendable object.
public Map<String, String[]>	Returns: `Map` containing parameter names as keys and parameter values as map values, or an empty `Map` if no parameters exist. The keys in the parameter map are of type String. The values in the parameter map are of type String array (`String[]`). getParameterMap() Deprecated As of version 3.0. Returns a `Map` of the parameters currently set on this portlet URL.
public void	setParameter(String the parameter name name, String the parameter value value) Deprecated As of version 3.0. Sets the given String parameter on this URL.
public void	setParameter(String the parameter name name, String... the parameter values values) Deprecated As of version 3.0. Sets a multi-valued String parameter on this URL.
public void	setParameters(Map<String, String[]> 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 and may not be null or the empty string (""). The values in the parameter map must be of type String array (`String[]`). Neither the values array nor any of its elements may be null; however, the empty string ("") is allowed as an array element. parameters) Deprecated As of version 3.0. Sets a parameter map for this URL.
public void	setProperty(String the key of the property key, String the value of the property value) Sets a String property on the URL.
public void	setSecure(boolean 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. secure) Indicates the security setting for this URL.
public String	Returns: the encoded URL as a string toString() Returns the portlet URL string representation to be embedded in the markup.
public void	write(Writer the writer to write the portlet URL to out) Writes the portlet URL to the output stream using the provided writer.
public void	write(Writer the writer to write the portlet URL to out, boolean denotes if the URL should be XML escaped before written to the output stream or not escapeXML) Writes the portlet URL to the output stream using the provided writer.

Method Detail

addProperty back to summary

addProperty	back to summary
public void addProperty(String key, String value) Adds a String property to an existing key on the URL. This method allows URL properties to have multiple values. Properties can be used by portlets to provide vendor specific information to the URL. Parameters key:String the key of the property value:String the value of the property Exceptions IllegalArgumentException: if key is `null`. Since 2.0

public void addProperty(String key, String value)

Adds a String property to an existing key on the URL.

This method allows URL properties to have multiple values.

Properties can be used by portlets to provide vendor specific information to the URL.

Parameters

key:String: the key of the property
value:String: the value of the property

Exceptions

IllegalArgumentException:: if key is null.

Since

2.0

append back to summary

append	back to summary
public Appendable append(Appendable out) throws IOException Appends the portlet URL to the appendable object. Note that the appended URL may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client. The appended URL is always XML escaped. For appending non-escaped URLs use `append(java.lang.Appendable, boolean)`. Parameters out:Appendable the object to receive the URL Returns:Appendable Appendable the Appendable object containing the URL Exceptions IOException: if an I/O error occurred while writing the URL Since 3.0

public Appendable append(Appendable out) throws IOException

Appends the portlet URL to the appendable object.

Note that the appended URL may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

The appended URL is always XML escaped. For appending non-escaped URLs use append(java.lang.Appendable, boolean).

Parameters

out:Appendable: the object to receive the URL

Returns:Appendable

Appendable the Appendable object containing the URL

Exceptions

IOException:: if an I/O error occurred while writing the URL

Since

3.0

append back to summary

append	back to summary
public Appendable append(Appendable out, boolean escapeXML) throws IOException Appends the portlet URL to the appendable object. If the parameter escapeXML is set to `true`, the URL will be escaped to be valid XML characters. The manner in which escaping is performed is implementation specific. If `escapeXML` is set to `false`, escaping the URL is left to the implementation. Note that the appended URL may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client. Parameters out:Appendable the object to receive the URL Returns:Appendable Appendable the Appendable object containing the URL Exceptions IOException: if an I/O error occurred while writing the URL Since 3.0

public Appendable append(Appendable out, boolean escapeXML) throws IOException

Appends the portlet URL to the appendable object.

If the parameter escapeXML is set to true, the URL will be escaped to be valid XML characters. The manner in which escaping is performed is implementation specific. If escapeXML is set to false, escaping the URL is left to the implementation.

Note that the appended URL may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

Parameters

out:Appendable: the object to receive the URL

Returns:Appendable

Appendable the Appendable object containing the URL

Exceptions

IOException:: if an I/O error occurred while writing the URL

Since

3.0

getParameterMap back to summary

getParameterMap	back to summary
public Map<String, String[]> getParameterMap() Deprecated As of version 3.0. Use `PortletURL#getRenderParameters()`, `ResourceURL#getResourceParameters()`, or `ActionURL#getActionParameters()` as required. Returns a `Map` of the parameters currently set on this portlet URL. The values in the returned `Map` are from type String array (`String[]`). The contents of the returned map are immutable in the sense that modifying the map does not directly affect the render parameters. In order to set the parameters using the modified map, the `BaseURL#setParameters(Map)` method must be used. If no parameters exist this method returns an empty `Map`. Returns:Map<String, String[]> `Map` containing parameter names as keys and parameter values as map values, or an empty `Map` if no parameters exist. The keys in the parameter map are of type String. The values in the parameter map are of type String array (`String[]`). Annotations @Deprecated Since 2.0

public Map<String, String[]> getParameterMap()

Deprecated

As of version 3.0. Use PortletURL#getRenderParameters(), ResourceURL#getResourceParameters(), or ActionURL#getActionParameters() as required.

Returns a Map of the parameters currently set on this portlet URL.

The values in the returned Map are from type String array (String[]).

The contents of the returned map are immutable in the sense that modifying the map does not directly affect the render parameters. In order to set the parameters using the modified map, the BaseURL#setParameters(Map) method must be used.

If no parameters exist this method returns an empty Map.

Returns:Map<String, String[]>

Map containing parameter names as keys and parameter values as map values, or an empty Map if no parameters exist. The keys in the parameter map are of type String. The values in the parameter map are of type String array (String[]).

Annotations

@Deprecated

Since

2.0

setParameter back to summary

setParameter	back to summary
public void setParameter(String name, String value) Deprecated As of version 3.0. Use `PortletURL#getRenderParameters()`, `ResourceURL#getResourceParameters()`, or `ActionURL#getActionParameters()` as required. Sets the given String parameter on this URL. This method replaces all parameter values with the given key, as allowed according to the rules for the URL. `RenderURL` - Both public and private parameters can be set. `ActionURL` - Action parameters (private parameters) are set as described. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request. `ResourceURL` - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request. 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. A parameter value of `null` indicates that this parameter should be removed. However, an empty string value ("") is allowed. A public render parameter cannot be removed by setting its value to `null`. Parameters name:String the parameter name value:String the parameter value Annotations @Deprecated Exceptions IllegalArgumentException: if name is `null`; if an attempt is made to set a public render parameter to `null`.

public void setParameter(String name, String value)

Deprecated

As of version 3.0. Use PortletURL#getRenderParameters(), ResourceURL#getResourceParameters(), or ActionURL#getActionParameters() as required.

Sets the given String parameter on this URL.

This method replaces all parameter values with the given key, as allowed according to the rules for the URL.

RenderURL - Both public and private parameters can be set.
ActionURL - Action parameters (private parameters) are set as described. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request.
ResourceURL - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request.

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.

A parameter value of null indicates that this parameter should be removed. However, an empty string value ("") is allowed.

A public render parameter cannot be removed by setting its value to null.

Parameters

name:String: the parameter name
value:String: the parameter value

Annotations

@Deprecated

Exceptions

IllegalArgumentException:: if name is null; if an attempt is made to set a public render parameter to null.

setParameter back to summary

setParameter	back to summary
public void setParameter(String name, String... values) Deprecated As of version 3.0. Use `PortletURL#getRenderParameters()`, `ResourceURL#getResourceParameters()`, or `ActionURL#getActionParameters()` as required. Sets a multi-valued String parameter on this URL. This method replaces all parameter values with the given key according to the rules for the URL. `RenderURL` - Both public and private parameters can be set. `ActionURL` - Action parameters (private parameters) are set as described. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request. `ResourceURL` - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request. 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. A values parameter of `null` indicates that this parameter should be removed. If the values parameter is not null, no element of the values array may be null. However, an empty string value ("") is allowed. Parameters name:String the parameter name values:String[] the parameter values Annotations @Deprecated Exceptions IllegalArgumentException: if name is `null`; if an element of the values array is `null`; if an attempt is made to set a public render parameter to `null`.

public void setParameter(String name, String... values)

Deprecated

As of version 3.0. Use PortletURL#getRenderParameters(), ResourceURL#getResourceParameters(), or ActionURL#getActionParameters() as required.

Sets a multi-valued String parameter on this URL.

This method replaces all parameter values with the given key according to the rules for the URL.

RenderURL - Both public and private parameters can be set.
ActionURL - Action parameters (private parameters) are set as described. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request.
ResourceURL - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request.

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.

A values parameter of null indicates that this parameter should be removed.

If the values parameter is not null, no element of the values array may be null. However, an empty string value ("") is allowed.

Parameters

name:String: the parameter name
values:String[]: the parameter values

Annotations

@Deprecated

Exceptions

IllegalArgumentException:: if name is null; if an element of the values array is null; if an attempt is made to set a public render parameter to null.

setParameters back to summary

setParameters	back to summary
public void setParameters(Map<String, String[]> parameters) Deprecated As of version 3.0. Use `PortletURL#getRenderParameters()`, `ResourceURL#getResourceParameters()`, or `ActionURL#getActionParameters()` as required. Sets a parameter map for this URL. All previously set parameters are cleared. This method can be used to set both public and private render parameters according to the rules for the URL. `RenderURL` - Both public and private parameters can be set. `ActionURL` - Action parameters are set. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request. `ResourceURL` - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request. These parameters will be accessible through the portlet request initiated through the URL. Any previously set private render parameter that is not contained in the new map is removed. However, public render parameters cannot be removed by excluding them from the map. Public render parameters that are not included in the map remain unchanged. 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<String, String[]> 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 and may not be null or the empty string (""). The values in the parameter map must be of type String array (`String[]`). Neither the values array nor any of its elements may be null; however, the empty string ("") is allowed as an array element. Annotations @Deprecated Exceptions IllegalArgumentException: if parameters is `null`, if any of the keys in the Map are `null`, if any of the keys is not a String, if any of the values is not a String array, or if any of the String array elements are null.

public void setParameters(Map<String, String[]> parameters)

Deprecated

As of version 3.0. Use PortletURL#getRenderParameters(), ResourceURL#getResourceParameters(), or ActionURL#getActionParameters() as required.

Sets a parameter map for this URL.

All previously set parameters are cleared.

This method can be used to set both public and private render parameters according to the rules for the URL.

RenderURL - Both public and private parameters can be set.
ActionURL - Action parameters are set. Public render parameters remain unchanged. If an action parameter has the same name as a public render parameter, both the action parameter value and the public render parameter value will be available during processing of the action request.
ResourceURL - Resource parameters are set. Public and private render parameters that were attached to the URL when it was created remain unchanged. If a resource parameter has the same name as a public or private render parameter, both the resource parameter value and the public or private render parameter value will be available during processing of the resource request.

These parameters will be accessible through the portlet request initiated through the URL.

Any previously set private render parameter that is not contained in the new map is removed. However, public render parameters cannot be removed by excluding them from the map. Public render parameters that are not included in the map remain unchanged.

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<String, String[]>: 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 and may not be null or the empty string (""). The values in the parameter map must be of type String array (String[]). Neither the values array nor any of its elements may be null; however, the empty string ("") is allowed as an array element.

Annotations

@Deprecated

Exceptions

IllegalArgumentException:: if parameters is null, if any of the keys in the Map are null, if any of the keys is not a String, if any of the values is not a String array, or if any of the String array elements are null.

setProperty back to summary

setProperty	back to summary
public void setProperty(String key, String value) Sets a String property on the URL. Properties can be used by portlets to provide vendor specific information to the URL. This method resets all properties previously added with the same key. Parameters key:String the key of the property value:String the value of the property Exceptions IllegalArgumentException: if key is `null`. Since 2.0

public void setProperty(String key, String value)

Sets a String property on the URL.

Properties can be used by portlets to provide vendor specific information to the URL.

This method resets all properties previously added with the same key.

Parameters

key:String: the key of the property
value:String: the value of the property

Exceptions

IllegalArgumentException:: if key is null.

Since

2.0

setSecure back to summary

setSecure	back to summary
public void setSecure(boolean secure) throws PortletSecurityException Indicates 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 should stay the same as the current request. Parameters secure:boolean 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. Exceptions PortletSecurityException: if the run-time environment does not support the indicated setting

public void setSecure(boolean secure) throws PortletSecurityException

Indicates 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 should stay the same as the current request.

Parameters

secure:boolean: 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.

Exceptions

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

toString back to summary

toString	back to summary
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. The returned URL is not XML escaped. For writing URLs to an output stream the `write(java.io.Writer)` or `write(java.io.Writer, boolean)` method should be used as these are more efficient. Returns:String the encoded URL as a string

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.

The returned URL is not XML escaped.

For writing URLs to an output stream the write(java.io.Writer) or write(java.io.Writer, boolean) method should be used as these are more efficient.

Returns:String: the encoded URL as a string

write back to summary

write	back to summary
public void write(Writer out) throws IOException Writes the portlet URL to the output stream using the provided writer. Note that the URL written to the output stream may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client. The URL written to the output stream is always XML escaped. For writing non-escaped URLs use `write(java.io.Writer, boolean)`. Parameters out:Writer the writer to write the portlet URL to Exceptions IOException: if an I/O error occurred while writing the URL Since 2.0

public void write(Writer out) throws IOException

Writes the portlet URL to the output stream using the provided writer.

Note that the URL written to the output stream may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

The URL written to the output stream is always XML escaped. For writing non-escaped URLs use write(java.io.Writer, boolean).

Parameters

out:Writer: the writer to write the portlet URL to

Exceptions

IOException:: if an I/O error occurred while writing the URL

Since

2.0

write back to summary

write	back to summary
public void write(Writer out, boolean escapeXML) throws IOException Writes the portlet URL to the output stream using the provided writer. If the parameter escapeXML is set to true the URL will be escaped to be valid XML characters, i.e. <, >, &, ', " will get converted into their corresponding character entity codes (< to &<, > to &>, & to &&, ' to &', " to &"). If escapeXML is set to false no escaping will be done. The manner in which escaping is performed is implementation specific. If `escapeXML` is set to `false`, escaping the URL is left to the implementation. Note that the URL written to the output stream may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client. Parameters out:Writer the writer to write the portlet URL to escapeXML:boolean denotes if the URL should be XML escaped before written to the output stream or not Exceptions IOException: if an I/O error occurred while writing the URL Since 2.0

public void write(Writer out, boolean escapeXML) throws IOException

Writes the portlet URL to the output stream using the provided writer. If the parameter escapeXML is set to true the URL will be escaped to be valid XML characters, i.e. <, >, &, ', " will get converted into their corresponding character entity codes (< to &<, > to &>, & to &&, ' to &', " to &"). If escapeXML is set to false no escaping will be done. The manner in which escaping is performed is implementation specific. If escapeXML is set to false, escaping the URL is left to the implementation.

Note that the URL written to the output stream may not be a valid URL, as it may be rewritten by the portal/portlet-container before returning the markup to the client.

Parameters

out:Writer: the writer to write the portlet URL to
escapeXML:boolean: denotes if the URL should be XML escaped before written to the output stream or not

Exceptions

IOException:: if an I/O error occurred while writing the URL

Since

2.0

public Interface BaseURL

Method Summary

Method Detail