You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pluto-scm@portals.apache.org by ms...@apache.org on 2016/04/14 14:28:54 UTC
[14/50] [abbrv] portals-pluto git commit: Renamed PortletState to
RenderState and made all corresponding code and documentation updates.
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/5a59b412/portlet-api/src/main/java/javax/portlet/BaseURL.java
----------------------------------------------------------------------
diff --git a/portlet-api/src/main/java/javax/portlet/BaseURL.java b/portlet-api/src/main/java/javax/portlet/BaseURL.java
index 1dd917c..4003207 100644
--- a/portlet-api/src/main/java/javax/portlet/BaseURL.java
+++ b/portlet-api/src/main/java/javax/portlet/BaseURL.java
@@ -1,432 +1,434 @@
-/* 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;
-
-/**
- * <div class="changed_modified_3_0">The
- * <CODE>BaseURL</CODE> defines the basic capabilities of a portlet URL
- * pointing back to the portlet.
- * <p>
- * If the portlet state is modified through this interface, the changes take
- * effect when the URL containing the modifications is triggered.
- * </div>
- * @see MutablePortletState
- * @since 2.0
- */
-public interface BaseURL extends PortletState {
-
- /**
- * <span class="changed_modified_3_0">Sets</span>
- * the given String parameter on this URL.
- * <p>
- * This method replaces all parameter values with the given key,
- * <span class="changed_added_3_0">as allowed
- * according to the rules for the URL.</span>
- * <div class="changed_added_3_0">
- * <ul>
- * <li>
- * <code>RenderURL</code> - Both public and private parameters can be set.
- * </li>
- * <li>
- * <code>ActionURL</code> - 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.
- * </li>
- * <li>
- * <code>ResourceURL</code> - 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.
- * </li>
- * </ul>
- * </div>
- * <p>
- * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
- * all parameter names and values. Developers should not encode them.
- * <p>
- * A portlet container may prefix the attribute names internally
- * in order to preserve a unique namespace for the portlet.
- * <p>
- * A parameter value of <code>null</code> indicates that this
- * parameter should be removed.
- * <span class="changed_added_3_0">However, an empty string value ("") is allowed.</span>
- * <p>
- * <span class="changed_added_3_0">A public render parameter cannot be removed by
- * setting its value to <code>null</code>.</span>
- *
- * @param name
- * the parameter name
- * @param value
- * the parameter value
- *
- * @exception java.lang.IllegalArgumentException
- * if name is <code>null</code>;
- * <span class="changed_added_3_0">if an attempt is made to set a public
- * render parameter to <code>null</code>.</span>
- * @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);
-
-
- /**
- * <span class="changed_modified_3_0">Sets
- * a multi-valued String parameter on</span> this URL.
- * <div class="changed_added_3_0">
- * <p>
- * This method replaces all parameter values with the given key
- * according to the rules for the URL.
- * <ul>
- * <li>
- * <code>RenderURL</code> - Both public and private parameters can be set.
- * </li>
- * <li>
- * <code>ActionURL</code> - 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.
- * </li>
- * <li>
- * <code>ResourceURL</code> - 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.
- * </li>
- * </ul>
- * </div>
- * <p>
- * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
- * all parameter names and values. Developers should not encode them.
- * <p>
- * A portlet container may prefix the attribute names internally
- * in order to preserve a unique namespace for the portlet.
- * <div class="changed_added_3_0">
- * <p>
- * A values parameter of <code>null</code> indicates that this
- * parameter should be removed.
- * <p>
- * If the values parameter is not null, no element of the values array may be null.
- * However, an empty string value ("") is allowed.
- * </div>
- *
- * @param name
- * the parameter name
- * @param values
- * the parameter values
- *
- * @exception java.lang.IllegalArgumentException
- * if name is <code>null</code>;
- * <span class="changed_added_3_0">if an element of the values array is <code>null</code>;
- * if an attempt is made to set a public render parameter to <code>null</code>.</span>
- *
- * @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);
-
-
- /**
- * <span class="changed_modified_3_0">Sets</span>
- * a parameter map for this URL.
- * <p>
- * <span class="changed_deleted_3_0">All previously set parameters are cleared.</span>
- * <div class="changed_added_3_0">
- * <p>
- * This method can be used to set both public and private render parameters
- * according to the rules for the URL.
- * <ul>
- * <li>
- * <code>RenderURL</code> - Both public and private parameters can be set.
- * </li>
- * <li>
- * <code>ActionURL</code> - 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.
- * </li>
- * <li>
- * <code>ResourceURL</code> - 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.
- * </li>
- * </ul>
- * <p>
- * These parameters will be accessible through the portlet request initiated through
- * the URL.
- * <p>
- * 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.
- * </div>
- * <p>
- * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
- * all parameter names and values. Developers should not encode them.
- * <p>
- * A portlet container may prefix the attribute names internally,
- * in order to preserve a unique namespace for the portlet.
- *
- * @param parameters
- * <span class="changed_modified_3_0">
- * 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 (<code>String[]</code>).
- * Neither the values array nor any of
- * its elements may be null; however, the empty string ("") is allowed as an array element.
- * </span>
- *
- * @exception java.lang.IllegalArgumentException
- * <span class="changed_modified_3_0">
- * if parameters is <code>null</code>, if any of the
- * keys in the Map are <code>null</code>, 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.
- * </span>
- *
- * @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<String, String[]> parameters);
-
-
- /**
- * Indicates the security setting for this URL.
- * <p>
- * Secure set to <code>true</code> indicates that the portlet requests
- * a secure connection between the client and the portlet window for
- * this URL. Secure set to <code>false</code> 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.<br>
- * 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.
- * <p>
- * The returned URL is not XML escaped.
- * <p>
- * 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 ();
-
-
- /**
- * <span class="changed_modified_3_0">Returns</span> a
- * <code>Map</code> of the parameters currently set on this portlet
- * URL.
- * <p>
- * The values in the returned <code>Map</code> are from type
- * String array (<code>String[]</code>).
- * <p class="changed_added_3_0">
- * 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.
- * </p>
- * <p>
- * If no parameters exist this method returns an empty <code>Map</code>.
- *
- * @return <code>Map</code> containing parameter names as
- * keys and parameter values as map values, or an empty <code>Map</code>
- * 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 (<code>String[]</code>).
- *
- * @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<String, String[]> getParameterMap();
-
- /**
- * Writes the portlet URL to the output stream using the provided writer.
- * <p>
- * 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.
- * <p>
- * 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.
- * <p>
- * 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;
-
-
- /**
- * <div class="changed_added_3_0">
- * Appends the portlet URL to the appendable object.
- * <p>
- * 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.
- * <p>
- * 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
- * </div>
- */
- public Appendable append(java.lang.Appendable out) throws java.io.IOException;
-
-
- /**
- * <div class="changed_added_3_0">
- * Appends the portlet URL to the appendable object.
- * <p>
- * 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.
- * <p>
- * 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
- * </div>
- */
- public Appendable append(java.lang.Appendable out, boolean escapeXML) throws java.io.IOException;
-
-
- /**
- * Adds a String property to an existing key on the URL.
- * <p>
- * This method allows URL properties to have multiple values.
- * <p>
- * 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 <code>null</code>.
- *
- * @since 2.0
- */
- public void addProperty(String key, String value);
-
-
- /**
- * Sets a String property on the URL.
- * <p>
- * Properties can be used by portlets to provide vendor specific information
- * to the URL.
- * <p>
- * 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 <code>null</code>.
- *
- * @since 2.0
- */
- public void setProperty(String key, String value);
-}
+/* 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;
+
+/**
+ * <div class="changed_modified_3_0">The
+ * <CODE>BaseURL</CODE> defines the basic capabilities of a portlet URL
+ * pointing back to the portlet.
+ * <p>
+ * If the render state is modified through this interface, the changes take
+ * effect when the URL containing the modifications is triggered.
+ * </div>
+ * @see MutableRenderState
+ * @since 2.0
+ */
+public interface BaseURL extends RenderState {
+
+ /**
+ * <span class="changed_modified_3_0">Sets</span>
+ * the given String parameter on this URL.
+ * <p>
+ * This method replaces all parameter values with the given key,
+ * <span class="changed_added_3_0">as allowed
+ * according to the rules for the URL.</span>
+ * <div class="changed_added_3_0">
+ * <ul>
+ * <li>
+ * <code>RenderURL</code> - Both public and private parameters can be set.
+ * </li>
+ * <li>
+ * <code>ActionURL</code> - 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.
+ * </li>
+ * <li>
+ * <code>ResourceURL</code> - 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.
+ * </li>
+ * </ul>
+ * </div>
+ * <p>
+ * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
+ * all parameter names and values. Developers should not encode them.
+ * <p>
+ * A portlet container may prefix the attribute names internally
+ * in order to preserve a unique namespace for the portlet.
+ * <p>
+ * A parameter value of <code>null</code> indicates that this
+ * parameter should be removed.
+ * <span class="changed_added_3_0">However, an empty string value ("") is allowed.</span>
+ * <p>
+ * <span class="changed_added_3_0">A public render parameter cannot be removed by
+ * setting its value to <code>null</code>.</span>
+ *
+ * @param name
+ * the parameter name
+ * @param value
+ * the parameter value
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>;
+ * <span class="changed_added_3_0">if an attempt is made to set a public
+ * render parameter to <code>null</code>.</span>
+ * @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);
+
+
+ /**
+ * <span class="changed_modified_3_0">Sets
+ * a multi-valued String parameter on</span> this URL.
+ * <div class="changed_added_3_0">
+ * <p>
+ * This method replaces all parameter values with the given key
+ * according to the rules for the URL.
+ * <ul>
+ * <li>
+ * <code>RenderURL</code> - Both public and private parameters can be set.
+ * </li>
+ * <li>
+ * <code>ActionURL</code> - 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.
+ * </li>
+ * <li>
+ * <code>ResourceURL</code> - 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.
+ * </li>
+ * </ul>
+ * </div>
+ * <p>
+ * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
+ * all parameter names and values. Developers should not encode them.
+ * <p>
+ * A portlet container may prefix the attribute names internally
+ * in order to preserve a unique namespace for the portlet.
+ * <div class="changed_added_3_0">
+ * <p>
+ * A values parameter of <code>null</code> indicates that this
+ * parameter should be removed.
+ * <p>
+ * If the values parameter is not null, no element of the values array may be null.
+ * However, an empty string value ("") is allowed.
+ * </div>
+ *
+ * @param name
+ * the parameter name
+ * @param values
+ * the parameter values
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>;
+ * <span class="changed_added_3_0">if an element of the values array is <code>null</code>;
+ * if an attempt is made to set a public render parameter to <code>null</code>.</span>
+ *
+ * @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);
+
+
+ /**
+ * <span class="changed_modified_3_0">Sets</span>
+ * a parameter map for this URL.
+ * <p>
+ * <span class="changed_deleted_3_0">All previously set parameters are cleared.</span>
+ * <div class="changed_added_3_0">
+ * <p>
+ * This method can be used to set both public and private render parameters
+ * according to the rules for the URL.
+ * <ul>
+ * <li>
+ * <code>RenderURL</code> - Both public and private parameters can be set.
+ * </li>
+ * <li>
+ * <code>ActionURL</code> - 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.
+ * </li>
+ * <li>
+ * <code>ResourceURL</code> - 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.
+ * </li>
+ * </ul>
+ * <p>
+ * These parameters will be accessible through the portlet request initiated through
+ * the URL.
+ * <p>
+ * 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.
+ * </div>
+ * <p>
+ * The <code>PortletURL</code> implementation 'x-www-form-urlencoded' encodes
+ * all parameter names and values. Developers should not encode them.
+ * <p>
+ * A portlet container may prefix the attribute names internally,
+ * in order to preserve a unique namespace for the portlet.
+ *
+ * @param parameters
+ * <span class="changed_modified_3_0">
+ * 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 (<code>String[]</code>).
+ * Neither the values array nor any of
+ * its elements may be null; however, the empty string ("") is allowed as an array element.
+ * </span>
+ *
+ * @exception java.lang.IllegalArgumentException
+ * <span class="changed_modified_3_0">
+ * if parameters is <code>null</code>, if any of the
+ * keys in the Map are <code>null</code>, 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.
+ * </span>
+ *
+ * @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<String, String[]> parameters);
+
+
+ /**
+ * Indicates the security setting for this URL.
+ * <p>
+ * Secure set to <code>true</code> indicates that the portlet requests
+ * a secure connection between the client and the portlet window for
+ * this URL. Secure set to <code>false</code> 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.<br>
+ * 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.
+ * <p>
+ * The returned URL is not XML escaped.
+ * <p>
+ * 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 ();
+
+
+ /**
+ * <span class="changed_modified_3_0">Returns</span> a
+ * <code>Map</code> of the parameters currently set on this portlet
+ * URL.
+ * <p>
+ * The values in the returned <code>Map</code> are from type
+ * String array (<code>String[]</code>).
+ * <p class="changed_added_3_0">
+ * 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.
+ * </p>
+ * <p>
+ * If no parameters exist this method returns an empty <code>Map</code>.
+ *
+ * @return <code>Map</code> containing parameter names as
+ * keys and parameter values as map values, or an empty <code>Map</code>
+ * 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 (<code>String[]</code>).
+ *
+ * @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<String, String[]> getParameterMap();
+
+
+ /**
+ * Writes the portlet URL to the output stream using the provided writer.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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;
+
+
+ /**
+ * <div class="changed_added_3_0">
+ * Appends the portlet URL to the appendable object.
+ * <p>
+ * 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.
+ * <p>
+ * 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
+ * </div>
+ */
+ public Appendable append(java.lang.Appendable out) throws java.io.IOException;
+
+
+ /**
+ * <div class="changed_added_3_0">
+ * Appends the portlet URL to the appendable object.
+ * <p>
+ * 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.
+ * <p>
+ * 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
+ * </div>
+ */
+ public Appendable append(java.lang.Appendable out, boolean escapeXML) throws java.io.IOException;
+
+
+ /**
+ * Adds a String property to an existing key on the URL.
+ * <p>
+ * This method allows URL properties to have multiple values.
+ * <p>
+ * 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 <code>null</code>.
+ *
+ * @since 2.0
+ */
+ public void addProperty(String key, String value);
+
+
+ /**
+ * Sets a String property on the URL.
+ * <p>
+ * Properties can be used by portlets to provide vendor specific information
+ * to the URL.
+ * <p>
+ * 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 <code>null</code>.
+ *
+ * @since 2.0
+ */
+ public void setProperty(String key, String value);
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/5a59b412/portlet-api/src/main/java/javax/portlet/MimeResponse.java
----------------------------------------------------------------------
diff --git a/portlet-api/src/main/java/javax/portlet/MimeResponse.java b/portlet-api/src/main/java/javax/portlet/MimeResponse.java
index f007ed8..e0e3f8d 100644
--- a/portlet-api/src/main/java/javax/portlet/MimeResponse.java
+++ b/portlet-api/src/main/java/javax/portlet/MimeResponse.java
@@ -1,650 +1,650 @@
-/* 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;
-
-/**
- * <span class="changed_modified_3_0">The</span>
- * <CODE>MimeResponse</CODE> defines the base interface to assist a
- * portlet in returning MIME content.
- *
- * @since 2.0
- */
-public interface MimeResponse extends PortletResponse {
-
-
- /**
- * <div class="changed_added_3_0">
- * Specifies processing when a URL is created.
- * </div>
- *
- * @see #createActionURL(Copy)
- * @see #createRenderURL(Copy)
- *
- * @since 3.0
- */
- public enum Copy {
-
- /**
- * <div class="changed_added_3_0">
- * Specifies that no parameters are to be copied when a URL is created.
- * </div>
- *
- * @since 3.0
- */
- NONE,
-
- /**
- * <div class="changed_added_3_0">
- * Specifies that the public and private render parameters set for
- * the current request are
- * be copied to the URL when it is created.
- * </div>
- *
- * @since 3.0
- */
- ALL,
-
- /**
- * <div class="changed_added_3_0">
- * Specifies that only the public render parameters set for the
- * current request are be copied to the URL when it is created.
- * </div>
- *
- * @since 3.0
- */
- PUBLIC;
- }
-
-
- /**
- * Property to set the expiration time in seconds for this response using
- * the <code>setProperty</code> method intended to be used in
- * forwarded or included servlets/JSPs.
- * <P>
- * If the expiration value is set to <code>0</code>, caching is disabled for this
- * portlet; if the value is set to <code>-1</code>, the cache does not expire.
- * <p>
- * A default can be defined in the portlet deployment descriptor
- * with the <code>expiration-cache</code> tag, otherwise it is <code>0</code>.
- * <p>
- * Non-integer values are treated as <code>0</code>.
- * <p>
- * The value is <code>"portlet.expiration-cache"</code>.
- *
- * @see CacheControl
- */
- public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
-
-
- /**
- * Property to set the cache scope for this response using the
- * <code>setProperty</code> method intended to be used in
- * forwarded or included servlets/JSPs.
- * <P>
- * Predefined cache scopes are: <code>PUBLIC_SCOPE</code> and <code>PRIVATE_SCOPE</code>.
- * <p>
- * A default can be defined in the portlet deployment descriptor
- * with the <code>cache-scope</code> tag, otherwise it is <code>PRIVATE_SCOPE</code>.
- * <p>
- * Values that are not either <code>PUBLIC_SCOPE</code> or <code>PRIVATE_SCOPE</code>
- * are treated as <code>PRIVATE_SCOPE</code>.
- * <p>
- * The value is <code>"portlet.cache-scope"</code>.
- *
- * @see CacheControl
- * @since 2.0
- */
- public static final String CACHE_SCOPE = "portlet.cache-scope";
-
- /**
- * Public cache scope, indicating that the cache entry can be shared across
- * users. The value is <code>"portlet.public-scope"</code>.
- *
- * @since 2.0
- */
- public static final String PUBLIC_SCOPE = "portlet.public-scope";
-
- /**
- * Private cache scope, indicating that the cache entry must not be shared
- * across users. The value is <code>"portlet.private-scope"</code>.
- *
- * @since 2.0
- */
- public static final String PRIVATE_SCOPE = "portlet.private-scope";
-
- /**
- * Property to tell the portlet container the new ETag for this response
- * intended to be used in forwarded or included servlets/JSPs.
- * <p>
- * This property needs to be set using the <code>setProperty</code> method.
- * <P>
- * The value is <code>"portlet.ETag "</code>.
- *
- * @see CacheControl
- * @since 2.0
- */
- public static final String ETAG = "portlet.ETag";
-
- /**
- * Property to tell the portlet container to use the cached markup
- * for the validation token provided in the request. This property
- * needs to be set using the <code>setProperty</code> method with a non-null
- * value and is intended to be used in forwarded or included servlets/JSPs.
- * The value itself is not evaluated.
- * <P>
- * The value is <code>"portlet.use-cached-content "</code>.
- *
- * @see CacheControl
- * @since 2.0
- */
- public static final String USE_CACHED_CONTENT = "portlet.use-cached-content";
-
-
- /**
- * Property intended to be a hint to the portal application that the returned
- * content is completely namespaced.
- * This includes all markup id elements, form fields, etc.
- * One example where this is might be used is for portal applications that
- * are form-based and thus need to re-write any forms included in the portlet
- * markup.
- * <p>
- * This property needs to be set using the <code>setProperty</code> method with a non-null
- * value. The value itself is not evaluated.
- * <p>
- * The value is <code>"X-JAVAX-PORTLET-NAMESPACED-RESPONSE"</code>.
- *
- * @since 2.0
- */
- public static final String NAMESPACED_RESPONSE = "X-JAVAX-PORTLET-NAMESPACED-RESPONSE";
-
- /**
- * Property intended to be a hint to the portal application that the provided
- * DOM element should be added to the markup head section of the response to the
- * client.
- * <p>
- * Support for this property is optional and the portlet can verify if the
- * calling portal supports this property via the <code>MARKUP_HEAD_ELEMENT_SUPPORT</code>
- * property on the <code>PortalContext</code>.
- * <p>
- * Even if the calling portal support this property delivery of the DOM
- * element to the client cannot be guaranteed, e.g. due to possible security
- * rules of the portal application or elements that conflict with the
- * response of other portlets.
- * <p>
- * This property needs to be set using the
- * <code>setProperty(String key,org.w3c.dom.Element element)</code>
- * method.
- * <p>
- * The value is <code>"javax.portlet.markup.head.element"</code>.
- *
- * @since 2.0
- */
- public static final String MARKUP_HEAD_ELEMENT = "javax.portlet.markup.head.element";
-
-
- /**
- * Returns the MIME type that can be used to contribute markup to the render
- * response.
- * <p>
- * If no content type was set previously using the {@link #setContentType}
- * method this method returns <code>null</code>.
- *
- * @see #setContentType
- *
- * @return the MIME type of the response, or <code>null</code> if no
- * content type is set
- */
- public String getContentType();
-
- /**
- * <span class="changed_modified_3_0">Sets</span>
- * the MIME type for the response. The portlet should set the
- * content type before calling {@link #getWriter} or
- * {@link #getPortletOutputStream}.
- * <span class="changed_modified_3_0">
- * If the content type is not set using this method, the preferred
- * content type as returned by {@link PortletRequest#getResponseContentType} is used.
- * </span>
- * <p>
- * Calling <code>setContentType</code> after <code>getWriter</code> or
- * <code>getOutputStream</code> does not change the content type.
- * <p>
- *
- * @param type
- * the content MIME type
- *
- * @exception java.lang.IllegalArgumentException
- * <span class="changed_added_3_0">
- * if the content type is invalid.
- * </span>
- *
- * @see PortletRequest#getResponseContentTypes
- * @see #getContentType
- */
- public void setContentType(String type);
-
- /**
- * Returns the name of the charset used for the MIME body sent in this
- * response.
- *
- * <p>
- * See <a href="http://ds.internic.net/rfc/rfc2045.txt">RFC 2047</a> for
- * more information about character encoding and MIME.
- *
- * @return a <code>String</code> specifying the name of the charset, for
- * example, <code>ISO-8859-1</code>
- *
- */
- public String getCharacterEncoding();
-
- /**
- * Returns a PrintWriter object that can send character text to the portal.
- * <p>
- * Before calling this method the content type of the render response should
- * be set using the {@link #setContentType} method.
- * <p>
- * Either this method or {@link #getPortletOutputStream} may be called to
- * write the body, not both.
- *
- * @return a <code>PrintWriter</code> object that can return character
- * data to the portal
- *
- * @exception java.io.IOException
- * if an input or output exception occurred
- * @exception java.lang.IllegalStateException
- * if the <code>getPortletOutputStream</code> method has
- * been called on this response.
- *
- * @see #setContentType
- * @see #getPortletOutputStream
- */
- public java.io.PrintWriter getWriter() throws java.io.IOException;
-
- /**
- * Returns the locale assigned to the response.
- *
- * @return Locale of this response
- */
- public java.util.Locale getLocale();
-
- /**
- * Sets the preferred buffer size for the body of the response. The portlet
- * container will use a buffer at least as large as the size requested.
- * <p>
- * This method must be called before any response body content is written;
- * if content has been written, or the portlet container does not support
- * buffering, this method may throw an <code>IllegalStateException</code>.
- *
- * @param size
- * the preferred buffer size
- *
- * @exception java.lang.IllegalStateException
- * if this method is called after content has been written,
- * or the portlet container does not support buffering
- *
- * @see #getBufferSize
- * @see #flushBuffer
- * @see #isCommitted
- * @see #reset
- */
- public void setBufferSize(int size);
-
- /**
- * Returns the actual buffer size used for the response. If no buffering is
- * used, this method returns 0.
- *
- * @return the actual buffer size used
- *
- * @see #setBufferSize
- * @see #flushBuffer
- * @see #isCommitted
- * @see #reset
- */
- public int getBufferSize();
-
- /**
- * Forces any content in the buffer to be written to the underlying output stream. A call to
- * this method automatically commits the response.
- *
- * @exception java.io.IOException
- * if an error occurred when writing the output
- *
- * @see #setBufferSize
- * @see #getBufferSize
- * @see #isCommitted
- * @see #reset
- */
- public void flushBuffer() throws java.io.IOException;
-
- /**
- * Clears the content of the underlying buffer in the response without
- * clearing properties set. If the response has been committed, this method
- * throws an <code>IllegalStateException</code>.
- *
- * @exception IllegalStateException
- * if this method is called after response is committed
- *
- * @see #setBufferSize
- * @see #getBufferSize
- * @see #isCommitted
- * @see #reset
- */
- public void resetBuffer();
-
- /**
- * Returns a boolean indicating if the response has been committed.
- *
- * @return a boolean indicating if the response has been committed
- *
- * @see #setBufferSize
- * @see #getBufferSize
- * @see #flushBuffer
- * @see #reset
- */
- public boolean isCommitted();
-
- /**
- * Clears any data that exists in the buffer as well as the properties set.
- * If the response has been committed, this method throws an
- * <code>IllegalStateException</code>.
- *
- * @exception java.lang.IllegalStateException
- * if the response has already been committed
- *
- * @see #setBufferSize
- * @see #getBufferSize
- * @see #flushBuffer
- * @see #isCommitted
- */
- public void reset();
-
- /**
- * Returns a <code>OutputStream</code> suitable for writing binary data in
- * the response. The portlet container does not encode the binary data.
- * <p>
- * Before calling this method the content type of the render response must
- * be set using the {@link #setContentType} method.
- * <p>
- * Calling <code>flush()</code> on the OutputStream commits the response.
- * <p>
- * Either this method or {@link #getWriter} may be called to write the body,
- * not both.
- *
- * @return a <code>OutputStream</code> for writing binary data
- *
- * @exception java.lang.IllegalStateException
- * if the <code>getWriter</code> method has been called on
- * this response.
- *
- * @exception java.io.IOException
- * if an input or output exception occurred
- *
- * @see #setContentType
- * @see #getWriter
- */
- public java.io.OutputStream getPortletOutputStream()
- throws java.io.IOException;
-
- /**
- * <div class="changed_modified_3_0">
- * Creates a render URL targeting the portlet.
- * Render URLs cause idempotent requests that move the portlet to a
- * new view state, for example, to view a different page of data.
- * <p>
- * If a request is triggered by the URL, it results in
- * a render request.
- * </div>
- * <div class="changed_added_3_0">
- * <p>
- * The returned render URL will not contain any private render parameters from the
- * current request.
- * </div>
- * <div class="changed_deleted_3_0">
- * <p>
- * The created URL will per default not contain any parameters of the
- * current render request.
- * </div>
- * <p>
- * The returned URL can be further extended by adding portlet-specific render
- * parameters, portlet mode, and window state.
- * If no portlet mode, window
- * state or security modifier is set on the URL, the values from the
- * current render or resource request are preserved.
- * <p>
- * <div class="changed_added_3_0">
- * Public render parameters do not need to be explicitly added to the returned
- * render URL, unless the public render parameter value is to be changed.
- * Any public render parameters associated with
- * the portlet will automatically be available during render request processing resulting
- * from activation of the URL.
- * <p>
- * If a public render parameter value is set or removed on a render URL, then the public
- * render parameter will be set to the new value or removed when the URL is activated.
- * <p>
- * The effect of this method is the same as calling {@link #createRenderURL(Copy)}
- * with the parameter set to PUBLIC.
- * </div>
- *
- * @return a portlet render URL
- */
- public <T extends PortletURL & RenderURL> T createRenderURL();
-
-
- /**
- * <div class="changed_added_3_0">
- * Creates a render URL targeting the portlet.
- * Render URLs cause idempotent requests that move the portlet to a
- * new view state, for example, to view a different page of data.
- * <p>
- * If a request is triggered by the URL, it results in
- * a render request.
- * <p>
- * The new render URL will contain render parameters from the
- * current request as specified by the <code>option</code> parameter.
- * <dl>
- * <dt>NONE</dt>
- * <dd>All public and private parameters are removed from the URL.</dd>
- * <dt>ALL</dt>
- * <dd>The public and private parameters governing the current
- * request are added to the URL.</dd>
- * <dt>PUBLIC</dt>
- * <dd>Only public parameters governing the current
- * request are added to the URL.</dd>
- * </dl>
- * The URL can be further extended by adding render
- * parameters, portlet mode, and window state.
- * If no additional portlet mode, window
- * state or security modifier is set on the URL, the values from the
- * current render or resource request are preserved.
- * <p>
- * If a public render parameter value is set or removed on a render URL, then the public
- * render parameter will be set to the new value or removed when the URL is activated.
- * </div>
- *
- * @param option
- * Specifies how current parameters are to be copied to the URL
- *
- * @see Copy
- *
- * @return a portlet render URL
- *
- * @since 3.0
- */
- public RenderURL createRenderURL(Copy option);
-
-
- /**
- * <div class="changed_modified_3_0">
- * Creates an action URL targeting the portlet.
- * Action URLs are used to create forms or links that, when triggered,
- * update the portlet state in a non-idempotent manner.
- * <p>
- * If a request is triggered by the URL, it results in
- * an action request.
- * </div>
- * <p>
- * The returned action URL will
- * <span class="changed_added_3_0">not contain any private render parameters</span>
- * <span class="changed_deleted_3_0">per default not contain any parameters</span>
- * from the current request.
- * <p>
- * The returned URL can be further extended by adding portlet-specific action
- * parameters, portlet mode, and window state.
- * If no additional portlet mode, window
- * state or security modifier is set on the URL, the values from the
- * current render or resource request are preserved.
- * <div class="changed_added_3_0">
- * <p>
- * Public render parameters do not need to be explicitly added to the returned
- * action URL, unless the public render parameter value is to be changed.
- * Any public render parameters associated with
- * the portlet will automatically be available during action request
- * processing resulting from activation of the URL.
- * <p>
- * If a public render parameter value is set or removed on an action URL,
- * then the public render parameter will be set to the new value or
- * removed when the URL is activated.
- * <p>
- * The effect of this method is the same as calling {@link #createRenderURL(Copy)}
- * with the parameter set to PUBLIC.
- * </div>
- *
- * @return a portlet action URL
- */
- public <T extends PortletURL & ActionURL> T createActionURL();
-
-
- /**
- * <div class="changed_added_3_0">
- * Creates an action URL targeting the portlet.
- * Action URLs are used to create forms or links that, when triggered,
- * update the portlet state in a non-idempotent manner.
- * <p>
- * If a request is triggered by the URL, it results in
- * an action request.
- * <p>
- * The new action URL will contain render parameters from the
- * current request as specified by the <code>option</code> parameter.
- * <dl>
- * <dt>NONE</dt>
- * <dd>All public and private parameters are removed from the URL.</dd>
- * <dt>ALL</dt>
- * <dd>The public and private parameters governing the current
- * request are added to the URL.</dd>
- * <dt>PUBLIC</dt>
- * <dd>Only public parameters governing the current
- * request are added to the URL.</dd>
- * </dl>
- * <p>
- * The returned URL can be further extended by adding action
- * parameters, portlet mode, and window state.
- * If no additional portlet mode, window
- * state or security modifier is set on the URL, the values from the
- * current render or resource request are preserved.
- * <p>
- * If a public render parameter value is set or removed on an action URL,
- * then the public render parameter will be set to the new value or
- * removed when the URL is activated.
- * </div>
- *
- * @param option
- * Specifies how current parameters are to be copied to the URL
- *
- * @see Copy
- *
- * @return a portlet action URL
- *
- * @since 3.0
- */
- public ActionURL createActionURL(Copy option);
-
-
- /**
- * <div class="changed_modified_3_0">
- * Creates a resource URL targeting the portlet.
- * Resource URLs are used to trigger requests for content that applies
- * to the current portlet view state.
- * <p>
- * If a request is triggered by the <code>ResourceURL</code>, it results in a serve
- * resource request of the <code>ResourceServingPortlet</code> interface.
- * <p>
- * The security settings can be changed for the URL. If the security settings are
- * not explicitly set, the values governing the current request
- * are preserved.
- * The current
- * render parameters, portlet mode, and window state are preserved
- * depending on the cacheability setting for the returned resource URL.
- * </div>
- * <div class="changed_added_3_0">
- * <p>
- * If cacheability is set to <code>PORTLET</code> or <code>PAGE</code>, the values of the render
- * parameters, portlet mode, and window state are preserved.
- * Otherwise, they will not be preserved.
- * <p>
- * If allowed by the cacheability setting, public and private render
- * parameters are added to the URL with their current values.
- * The render parameter values cannot be changed on the URL.
- * <p>
- * The URL can be further extended by adding portlet-specific resource
- * parameters.
- * <p>
- * The URL will contain the current
- * cacheability setting of the parent resource by default.
- * If no parent resource is available, <code>PAGE</code> is the default.
- * </div>
- * <div class="changed_deleted_3_0">
- * If a request is triggered by the PortletURL, it results in a serve
- * resource request of the <code>ResourceServingPortlet</code> interface.
- * <p>
- * The returned URL can be further extended by adding portlet-specific
- * parameters .
- * <p>
- * The created URL will by default contain the current
- * cacheability setting of the parent resource.
- * If no parent resource is available, <code>PAGE</code> is the default.
- * </div>
- *
- * @since 2.0
- * @return a portlet resource URL
- */
- public ResourceURL createResourceURL();
-
-
-
- /**
- * Returns the cache control object allowing to set
- * specific cache settings valid for the markup
- * returned in this response.
- *
- * @return Cache control for the current response.
- *
- * @since 2.0
- */
- public CacheControl getCacheControl();
-
-
-
-
-}
+/* 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;
+
+/**
+ * <span class="changed_modified_3_0">The</span>
+ * <CODE>MimeResponse</CODE> defines the base interface to assist a
+ * portlet in returning MIME content.
+ *
+ * @since 2.0
+ */
+public interface MimeResponse extends PortletResponse {
+
+
+ /**
+ * <div class="changed_added_3_0">
+ * Specifies processing when a URL is created.
+ * </div>
+ *
+ * @see #createActionURL(Copy)
+ * @see #createRenderURL(Copy)
+ *
+ * @since 3.0
+ */
+ public enum Copy {
+
+ /**
+ * <div class="changed_added_3_0">
+ * Specifies that no parameters are to be copied when a URL is created.
+ * </div>
+ *
+ * @since 3.0
+ */
+ NONE,
+
+ /**
+ * <div class="changed_added_3_0">
+ * Specifies that the public and private render parameters set for
+ * the current request are
+ * be copied to the URL when it is created.
+ * </div>
+ *
+ * @since 3.0
+ */
+ ALL,
+
+ /**
+ * <div class="changed_added_3_0">
+ * Specifies that only the public render parameters set for the
+ * current request are be copied to the URL when it is created.
+ * </div>
+ *
+ * @since 3.0
+ */
+ PUBLIC;
+ }
+
+
+ /**
+ * Property to set the expiration time in seconds for this response using
+ * the <code>setProperty</code> method intended to be used in
+ * forwarded or included servlets/JSPs.
+ * <P>
+ * If the expiration value is set to <code>0</code>, caching is disabled for this
+ * portlet; if the value is set to <code>-1</code>, the cache does not expire.
+ * <p>
+ * A default can be defined in the portlet deployment descriptor
+ * with the <code>expiration-cache</code> tag, otherwise it is <code>0</code>.
+ * <p>
+ * Non-integer values are treated as <code>0</code>.
+ * <p>
+ * The value is <code>"portlet.expiration-cache"</code>.
+ *
+ * @see CacheControl
+ */
+ public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
+
+
+ /**
+ * Property to set the cache scope for this response using the
+ * <code>setProperty</code> method intended to be used in
+ * forwarded or included servlets/JSPs.
+ * <P>
+ * Predefined cache scopes are: <code>PUBLIC_SCOPE</code> and <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * A default can be defined in the portlet deployment descriptor
+ * with the <code>cache-scope</code> tag, otherwise it is <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * Values that are not either <code>PUBLIC_SCOPE</code> or <code>PRIVATE_SCOPE</code>
+ * are treated as <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * The value is <code>"portlet.cache-scope"</code>.
+ *
+ * @see CacheControl
+ * @since 2.0
+ */
+ public static final String CACHE_SCOPE = "portlet.cache-scope";
+
+ /**
+ * Public cache scope, indicating that the cache entry can be shared across
+ * users. The value is <code>"portlet.public-scope"</code>.
+ *
+ * @since 2.0
+ */
+ public static final String PUBLIC_SCOPE = "portlet.public-scope";
+
+ /**
+ * Private cache scope, indicating that the cache entry must not be shared
+ * across users. The value is <code>"portlet.private-scope"</code>.
+ *
+ * @since 2.0
+ */
+ public static final String PRIVATE_SCOPE = "portlet.private-scope";
+
+ /**
+ * Property to tell the portlet container the new ETag for this response
+ * intended to be used in forwarded or included servlets/JSPs.
+ * <p>
+ * This property needs to be set using the <code>setProperty</code> method.
+ * <P>
+ * The value is <code>"portlet.ETag "</code>.
+ *
+ * @see CacheControl
+ * @since 2.0
+ */
+ public static final String ETAG = "portlet.ETag";
+
+ /**
+ * Property to tell the portlet container to use the cached markup
+ * for the validation token provided in the request. This property
+ * needs to be set using the <code>setProperty</code> method with a non-null
+ * value and is intended to be used in forwarded or included servlets/JSPs.
+ * The value itself is not evaluated.
+ * <P>
+ * The value is <code>"portlet.use-cached-content "</code>.
+ *
+ * @see CacheControl
+ * @since 2.0
+ */
+ public static final String USE_CACHED_CONTENT = "portlet.use-cached-content";
+
+
+ /**
+ * Property intended to be a hint to the portal application that the returned
+ * content is completely namespaced.
+ * This includes all markup id elements, form fields, etc.
+ * One example where this is might be used is for portal applications that
+ * are form-based and thus need to re-write any forms included in the portlet
+ * markup.
+ * <p>
+ * This property needs to be set using the <code>setProperty</code> method with a non-null
+ * value. The value itself is not evaluated.
+ * <p>
+ * The value is <code>"X-JAVAX-PORTLET-NAMESPACED-RESPONSE"</code>.
+ *
+ * @since 2.0
+ */
+ public static final String NAMESPACED_RESPONSE = "X-JAVAX-PORTLET-NAMESPACED-RESPONSE";
+
+ /**
+ * Property intended to be a hint to the portal application that the provided
+ * DOM element should be added to the markup head section of the response to the
+ * client.
+ * <p>
+ * Support for this property is optional and the portlet can verify if the
+ * calling portal supports this property via the <code>MARKUP_HEAD_ELEMENT_SUPPORT</code>
+ * property on the <code>PortalContext</code>.
+ * <p>
+ * Even if the calling portal support this property delivery of the DOM
+ * element to the client cannot be guaranteed, e.g. due to possible security
+ * rules of the portal application or elements that conflict with the
+ * response of other portlets.
+ * <p>
+ * This property needs to be set using the
+ * <code>setProperty(String key,org.w3c.dom.Element element)</code>
+ * method.
+ * <p>
+ * The value is <code>"javax.portlet.markup.head.element"</code>.
+ *
+ * @since 2.0
+ */
+ public static final String MARKUP_HEAD_ELEMENT = "javax.portlet.markup.head.element";
+
+
+ /**
+ * Returns the MIME type that can be used to contribute markup to the render
+ * response.
+ * <p>
+ * If no content type was set previously using the {@link #setContentType}
+ * method this method returns <code>null</code>.
+ *
+ * @see #setContentType
+ *
+ * @return the MIME type of the response, or <code>null</code> if no
+ * content type is set
+ */
+ public String getContentType();
+
+ /**
+ * <span class="changed_modified_3_0">Sets</span>
+ * the MIME type for the response. The portlet should set the
+ * content type before calling {@link #getWriter} or
+ * {@link #getPortletOutputStream}.
+ * <span class="changed_modified_3_0">
+ * If the content type is not set using this method, the preferred
+ * content type as returned by {@link PortletRequest#getResponseContentType} is used.
+ * </span>
+ * <p>
+ * Calling <code>setContentType</code> after <code>getWriter</code> or
+ * <code>getOutputStream</code> does not change the content type.
+ * <p>
+ *
+ * @param type
+ * the content MIME type
+ *
+ * @exception java.lang.IllegalArgumentException
+ * <span class="changed_added_3_0">
+ * if the content type is invalid.
+ * </span>
+ *
+ * @see PortletRequest#getResponseContentTypes
+ * @see #getContentType
+ */
+ public void setContentType(String type);
+
+ /**
+ * Returns the name of the charset used for the MIME body sent in this
+ * response.
+ *
+ * <p>
+ * See <a href="http://ds.internic.net/rfc/rfc2045.txt">RFC 2047</a> for
+ * more information about character encoding and MIME.
+ *
+ * @return a <code>String</code> specifying the name of the charset, for
+ * example, <code>ISO-8859-1</code>
+ *
+ */
+ public String getCharacterEncoding();
+
+ /**
+ * Returns a PrintWriter object that can send character text to the portal.
+ * <p>
+ * Before calling this method the content type of the render response should
+ * be set using the {@link #setContentType} method.
+ * <p>
+ * Either this method or {@link #getPortletOutputStream} may be called to
+ * write the body, not both.
+ *
+ * @return a <code>PrintWriter</code> object that can return character
+ * data to the portal
+ *
+ * @exception java.io.IOException
+ * if an input or output exception occurred
+ * @exception java.lang.IllegalStateException
+ * if the <code>getPortletOutputStream</code> method has
+ * been called on this response.
+ *
+ * @see #setContentType
+ * @see #getPortletOutputStream
+ */
+ public java.io.PrintWriter getWriter() throws java.io.IOException;
+
+ /**
+ * Returns the locale assigned to the response.
+ *
+ * @return Locale of this response
+ */
+ public java.util.Locale getLocale();
+
+ /**
+ * Sets the preferred buffer size for the body of the response. The portlet
+ * container will use a buffer at least as large as the size requested.
+ * <p>
+ * This method must be called before any response body content is written;
+ * if content has been written, or the portlet container does not support
+ * buffering, this method may throw an <code>IllegalStateException</code>.
+ *
+ * @param size
+ * the preferred buffer size
+ *
+ * @exception java.lang.IllegalStateException
+ * if this method is called after content has been written,
+ * or the portlet container does not support buffering
+ *
+ * @see #getBufferSize
+ * @see #flushBuffer
+ * @see #isCommitted
+ * @see #reset
+ */
+ public void setBufferSize(int size);
+
+ /**
+ * Returns the actual buffer size used for the response. If no buffering is
+ * used, this method returns 0.
+ *
+ * @return the actual buffer size used
+ *
+ * @see #setBufferSize
+ * @see #flushBuffer
+ * @see #isCommitted
+ * @see #reset
+ */
+ public int getBufferSize();
+
+ /**
+ * Forces any content in the buffer to be written to the underlying output stream. A call to
+ * this method automatically commits the response.
+ *
+ * @exception java.io.IOException
+ * if an error occurred when writing the output
+ *
+ * @see #setBufferSize
+ * @see #getBufferSize
+ * @see #isCommitted
+ * @see #reset
+ */
+ public void flushBuffer() throws java.io.IOException;
+
+ /**
+ * Clears the content of the underlying buffer in the response without
+ * clearing properties set. If the response has been committed, this method
+ * throws an <code>IllegalStateException</code>.
+ *
+ * @exception IllegalStateException
+ * if this method is called after response is committed
+ *
+ * @see #setBufferSize
+ * @see #getBufferSize
+ * @see #isCommitted
+ * @see #reset
+ */
+ public void resetBuffer();
+
+ /**
+ * Returns a boolean indicating if the response has been committed.
+ *
+ * @return a boolean indicating if the response has been committed
+ *
+ * @see #setBufferSize
+ * @see #getBufferSize
+ * @see #flushBuffer
+ * @see #reset
+ */
+ public boolean isCommitted();
+
+ /**
+ * Clears any data that exists in the buffer as well as the properties set.
+ * If the response has been committed, this method throws an
+ * <code>IllegalStateException</code>.
+ *
+ * @exception java.lang.IllegalStateException
+ * if the response has already been committed
+ *
+ * @see #setBufferSize
+ * @see #getBufferSize
+ * @see #flushBuffer
+ * @see #isCommitted
+ */
+ public void reset();
+
+ /**
+ * Returns a <code>OutputStream</code> suitable for writing binary data in
+ * the response. The portlet container does not encode the binary data.
+ * <p>
+ * Before calling this method the content type of the render response must
+ * be set using the {@link #setContentType} method.
+ * <p>
+ * Calling <code>flush()</code> on the OutputStream commits the response.
+ * <p>
+ * Either this method or {@link #getWriter} may be called to write the body,
+ * not both.
+ *
+ * @return a <code>OutputStream</code> for writing binary data
+ *
+ * @exception java.lang.IllegalStateException
+ * if the <code>getWriter</code> method has been called on
+ * this response.
+ *
+ * @exception java.io.IOException
+ * if an input or output exception occurred
+ *
+ * @see #setContentType
+ * @see #getWriter
+ */
+ public java.io.OutputStream getPortletOutputStream()
+ throws java.io.IOException;
+
+ /**
+ * <div class="changed_modified_3_0">
+ * Creates a render URL targeting the portlet.
+ * Render URLs cause idempotent requests that move the portlet to a
+ * new view state, for example, to view a different page of data.
+ * <p>
+ * If a request is triggered by the URL, it results in
+ * a render request.
+ * </div>
+ * <div class="changed_added_3_0">
+ * <p>
+ * The returned render URL will not contain any private render parameters from the
+ * current request.
+ * </div>
+ * <div class="changed_deleted_3_0">
+ * <p>
+ * The created URL will per default not contain any parameters of the
+ * current render request.
+ * </div>
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific render
+ * parameters, portlet mode, and window state.
+ * If no portlet mode, window
+ * state or security modifier is set on the URL, the values from the
+ * current render or resource request are preserved.
+ * <p>
+ * <div class="changed_added_3_0">
+ * Public render parameters do not need to be explicitly added to the returned
+ * render URL, unless the public render parameter value is to be changed.
+ * Any public render parameters associated with
+ * the portlet will automatically be available during render request processing resulting
+ * from activation of the URL.
+ * <p>
+ * If a public render parameter value is set or removed on a render URL, then the public
+ * render parameter will be set to the new value or removed when the URL is activated.
+ * <p>
+ * The effect of this method is the same as calling {@link #createRenderURL(Copy)}
+ * with the parameter set to PUBLIC.
+ * </div>
+ *
+ * @return a portlet render URL
+ */
+ public <T extends PortletURL & RenderURL> T createRenderURL();
+
+
+ /**
+ * <div class="changed_added_3_0">
+ * Creates a render URL targeting the portlet.
+ * Render URLs cause idempotent requests that move the portlet to a
+ * new view state, for example, to view a different page of data.
+ * <p>
+ * If a request is triggered by the URL, it results in
+ * a render request.
+ * <p>
+ * The new render URL will contain render parameters from the
+ * current request as specified by the <code>option</code> parameter.
+ * <dl>
+ * <dt>NONE</dt>
+ * <dd>All public and private parameters are removed from the URL.</dd>
+ * <dt>ALL</dt>
+ * <dd>The public and private parameters governing the current
+ * request are added to the URL.</dd>
+ * <dt>PUBLIC</dt>
+ * <dd>Only public parameters governing the current
+ * request are added to the URL.</dd>
+ * </dl>
+ * The URL can be further extended by adding render
+ * parameters, portlet mode, and window state.
+ * If no additional portlet mode, window
+ * state or security modifier is set on the URL, the values from the
+ * current render or resource request are preserved.
+ * <p>
+ * If a public render parameter value is set or removed on a render URL, then the public
+ * render parameter will be set to the new value or removed when the URL is activated.
+ * </div>
+ *
+ * @param option
+ * Specifies how current parameters are to be copied to the URL
+ *
+ * @see Copy
+ *
+ * @return a portlet render URL
+ *
+ * @since 3.0
+ */
+ public RenderURL createRenderURL(Copy option);
+
+
+ /**
+ * <div class="changed_modified_3_0">
+ * Creates an action URL targeting the portlet.
+ * Action URLs are used to create forms or links that, when triggered,
+ * update the render state in a non-idempotent manner.
+ * <p>
+ * If a request is triggered by the URL, it results in
+ * an action request.
+ * </div>
+ * <p>
+ * The returned action URL will
+ * <span class="changed_added_3_0">not contain any private render parameters</span>
+ * <span class="changed_deleted_3_0">per default not contain any parameters</span>
+ * from the current request.
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific action
+ * parameters, portlet mode, and window state.
+ * If no additional portlet mode, window
+ * state or security modifier is set on the URL, the values from the
+ * current render or resource request are preserved.
+ * <div class="changed_added_3_0">
+ * <p>
+ * Public render parameters do not need to be explicitly added to the returned
+ * action URL, unless the public render parameter value is to be changed.
+ * Any public render parameters associated with
+ * the portlet will automatically be available during action request
+ * processing resulting from activation of the URL.
+ * <p>
+ * If a public render parameter value is set or removed on an action URL,
+ * then the public render parameter will be set to the new value or
+ * removed when the URL is activated.
+ * <p>
+ * The effect of this method is the same as calling {@link #createRenderURL(Copy)}
+ * with the parameter set to PUBLIC.
+ * </div>
+ *
+ * @return a portlet action URL
+ */
+ public <T extends PortletURL & ActionURL> T createActionURL();
+
+
+ /**
+ * <div class="changed_added_3_0">
+ * Creates an action URL targeting the portlet.
+ * Action URLs are used to create forms or links that, when triggered,
+ * update the render state in a non-idempotent manner.
+ * <p>
+ * If a request is triggered by the URL, it results in
+ * an action request.
+ * <p>
+ * The new action URL will contain render parameters from the
+ * current request as specified by the <code>option</code> parameter.
+ * <dl>
+ * <dt>NONE</dt>
+ * <dd>All public and private parameters are removed from the URL.</dd>
+ * <dt>ALL</dt>
+ * <dd>The public and private parameters governing the current
+ * request are added to the URL.</dd>
+ * <dt>PUBLIC</dt>
+ * <dd>Only public parameters governing the current
+ * request are added to the URL.</dd>
+ * </dl>
+ * <p>
+ * The returned URL can be further extended by adding action
+ * parameters, portlet mode, and window state.
+ * If no additional portlet mode, window
+ * state or security modifier is set on the URL, the values from the
+ * current render or resource request are preserved.
+ * <p>
+ * If a public render parameter value is set or removed on an action URL,
+ * then the public render parameter will be set to the new value or
+ * removed when the URL is activated.
+ * </div>
+ *
+ * @param option
+ * Specifies how current parameters are to be copied to the URL
+ *
+ * @see Copy
+ *
+ * @return a portlet action URL
+ *
+ * @since 3.0
+ */
+ public ActionURL createActionURL(Copy option);
+
+
+ /**
+ * <div class="changed_modified_3_0">
+ * Creates a resource URL targeting the portlet.
+ * Resource URLs are used to trigger requests for content that applies
+ * to the current portlet view state.
+ * <p>
+ * If a request is triggered by the <code>ResourceURL</code>, it results in a serve
+ * resource request of the <code>ResourceServingPortlet</code> interface.
+ * <p>
+ * The security settings can be changed for the URL. If the security settings are
+ * not explicitly set, the values governing the current request
+ * are preserved.
+ * The current
+ * render parameters, portlet mode, and window state are preserved
+ * depending on the cacheability setting for the returned resource URL.
+ * </div>
+ * <div class="changed_added_3_0">
+ * <p>
+ * If cacheability is set to <code>PORTLET</code> or <code>PAGE</code>, the values of the render
+ * parameters, portlet mode, and window state are preserved.
+ * Otherwise, they will not be preserved.
+ * <p>
+ * If allowed by the cacheability setting, public and private render
+ * parameters are added to the URL with their current values.
+ * The render parameter values cannot be changed on the URL.
+ * <p>
+ * The URL can be further extended by adding portlet-specific resource
+ * parameters.
+ * <p>
+ * The URL will contain the current
+ * cacheability setting of the parent resource by default.
+ * If no parent resource is available, <code>PAGE</code> is the default.
+ * </div>
+ * <div class="changed_deleted_3_0">
+ * If a request is triggered by the PortletURL, it results in a serve
+ * resource request of the <code>ResourceServingPortlet</code> interface.
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific
+ * parameters .
+ * <p>
+ * The created URL will by default contain the current
+ * cacheability setting of the parent resource.
+ * If no parent resource is available, <code>PAGE</code> is the default.
+ * </div>
+ *
+ * @since 2.0
+ * @return a portlet resource URL
+ */
+ public ResourceURL createResourceURL();
+
+
+
+ /**
+ * Returns the cache control object allowing to set
+ * specific cache settings valid for the markup
+ * returned in this response.
+ *
+ * @return Cache control for the current response.
+ *
+ * @since 2.0
+ */
+ public CacheControl getCacheControl();
+
+
+
+
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/5a59b412/portlet-api/src/main/java/javax/portlet/Mutable.java
----------------------------------------------------------------------
diff --git a/portlet-api/src/main/java/javax/portlet/Mutable.java b/portlet-api/src/main/java/javax/portlet/Mutable.java
index eabeb12..177421e 100644
--- a/portlet-api/src/main/java/javax/portlet/Mutable.java
+++ b/portlet-api/src/main/java/javax/portlet/Mutable.java
@@ -30,7 +30,7 @@ package javax.portlet;
* This is a marker interface indicating that the implementing object contains
* methods for updating portelt state information.
* </div>
- * @see MutablePortletState
+ * @see MutableRenderState
* @see MutablePortletParameters
* @since 3.0
*/
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/5a59b412/portlet-api/src/main/java/javax/portlet/MutableActionParameters.java
----------------------------------------------------------------------
diff --git a/portlet-api/src/main/java/javax/portlet/MutableActionParameters.java b/portlet-api/src/main/java/javax/portlet/MutableActionParameters.java
index e0100d3..2426dc6 100644
--- a/portlet-api/src/main/java/javax/portlet/MutableActionParameters.java
+++ b/portlet-api/src/main/java/javax/portlet/MutableActionParameters.java
@@ -40,10 +40,10 @@ package javax.portlet;
* The modified parameters will be available during requests
* triggered by the URL.
* <p>
- * {@link PortletState} provides a description of the portlet state.
+ * {@link RenderState} provides a description of the render state.
* {@link PortletParameters} provides a description of the parameter concept.
* </div>
- * @see PortletState
+ * @see RenderState
* @see PortletParameters
* @see ActionParameters
* @see ActionRequest
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/5a59b412/portlet-api/src/main/java/javax/portlet/MutablePortletParameters.java
----------------------------------------------------------------------
diff --git a/portlet-api/src/main/java/javax/portlet/MutablePortletParameters.java b/portlet-api/src/main/java/javax/portlet/MutablePortletParameters.java
index 7c48fd8..436551a 100644
--- a/portlet-api/src/main/java/javax/portlet/MutablePortletParameters.java
+++ b/portlet-api/src/main/java/javax/portlet/MutablePortletParameters.java
@@ -29,14 +29,14 @@ import java.util.Set;
/**
* <div class="changed_added_3_0">
* The <CODE>MutablePortletParameters</CODE> provides methods that allow
- * setting parameters to define a potential future portlet state.
+ * setting parameters to define a potential future render state.
* <p>
- * {@link PortletState} provides a description of the portlet state.
+ * {@link RenderState} provides a description of the render state.
* {@link PortletParameters} provides a description of the parameter concept.
* </div>
- * @see PortletState
+ * @see RenderState
* @see PortletParameters
- * @see MutablePortletState
+ * @see MutableRenderState
* @since 3.0
*/
public interface MutablePortletParameters extends PortletParameters, Mutable {