javax.portlet.BaseURL Maven / Gradle / Ivy
Show all versions of portlet-api Show documentation
/* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* This source code implements specifications defined by the Java
* Community Process. In order to remain compliant with the specification
* DO NOT add / change / or delete method signatures!
*/
package javax.portlet;
/**
* The
* BaseURL defines the basic capabilities of a portlet URL
* pointing back to the portlet.
*
* If the render state is modified through this interface, the changes take
* effect when the URL containing the modifications is triggered.
*
* @see MutableRenderState
* @since 2.0
*/
public interface BaseURL extends RenderState {
/**
* 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.
*
* @param name
* the parameter name
* @param value
* the parameter value
*
* @exception java.lang.IllegalArgumentException
* if name is null;
* if an attempt is made to set a public
* render parameter to null.
* @deprecated As of version 3.0. Use {@link PortletURL#getRenderParameters()},
* {@link ResourceURL#getResourceParameters()},
* or {@link ActionURL#getActionParameters()} as required.
*/
@Deprecated
public void setParameter (String name, String value);
/**
* 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.
*
*
* @param name
* the parameter name
* @param values
* the parameter values
*
* @exception java.lang.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.
*
* @deprecated As of version 3.0. Use {@link PortletURL#getRenderParameters()},
* {@link ResourceURL#getResourceParameters()},
* or {@link ActionURL#getActionParameters()} as required.
*/
@Deprecated
public void setParameter (String name, String... values);
/**
* 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.
*
* @param 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 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.
*
*
* @exception java.lang.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.
*
*
* @deprecated As of version 3.0. Use {@link PortletURL#getRenderParameters()},
* {@link ResourceURL#getResourceParameters()},
* or {@link ActionURL#getActionParameters()} as required.
*/
@Deprecated
public void setParameters(java.util.Map parameters);
/**
* 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.
*
* @param 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
*/
public void setSecure (boolean secure) throws PortletSecurityException;
/**
* 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 {@link #write(java.io.Writer)} or
* {@link #write(java.io.Writer, boolean)} method should be used as these are
* more efficient.
*
* @return the encoded URL as a string
*/
public String toString ();
/**
* 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 {@link BaseURL#setParameters(Map)} method must be used.
*
*
* If no parameters exist this method returns an empty Map.
*
* @return 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[]).
*
* @since 2.0
*
* @deprecated As of version 3.0. Use {@link PortletURL#getRenderParameters()},
* {@link ResourceURL#getResourceParameters()},
* or {@link ActionURL#getActionParameters()} as required.
*/
@Deprecated
public java.util.Map getParameterMap();
/**
* 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 {@link #write(java.io.Writer, boolean)}.
*
* @param out the writer to write the portlet URL to
* @throws java.io.IOException if an I/O error occurred while writing the URL
*
* @since 2.0
*/
public void write(java.io.Writer out) throws java.io.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.
*
* @param out the writer to write the portlet URL to
* @param escapeXML denotes if the URL should be XML escaped before written to the output
* stream or not
* @throws java.io.IOException if an I/O error occurred while writing the URL
*
* @since 2.0
*/
public void write(java.io.Writer out, boolean escapeXML) throws java.io.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 {@link #append(java.lang.Appendable, boolean)}.
*
* @param out the object to receive the URL
*
* @return Appendable the Appendable object containing the URL
*
* @throws java.io.IOException if an I/O error occurred while writing the URL
*
* @since 3.0
*
*/
public Appendable append(java.lang.Appendable out) throws java.io.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.
*
* @param out the object to receive the URL
*
* @return Appendable the Appendable object containing the URL
*
* @throws java.io.IOException if an I/O error occurred while writing the URL
*
* @since 3.0
*
*/
public Appendable append(java.lang.Appendable out, boolean escapeXML) throws java.io.IOException;
/**
* 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.
*
* @param key
* the key of the property
* @param value
* the value of the property
*
* @exception java.lang.IllegalArgumentException
* if key is null.
*
* @since 2.0
*/
public void addProperty(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.
*
* @param key
* the key of the property
* @param value
* the value of the property
*
* @exception java.lang.IllegalArgumentException
* if key is null.
*
* @since 2.0
*/
public void setProperty(String key, String value);
}