Author: fmeschbe
Date: Mon Feb 17 09:15:07 2014
New Revision: 1568913
URL: http://svn.apache.org/r1568913
Log:
JavaDoc
Modified:
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/NamedRequestParameter.java
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/ParameterSupport.java
Modified:
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/NamedRequestParameter.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/NamedRequestParameter.java?rev=1568913&r1=1568912&r2=1568913&view=diff
==============================================================================
---
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/NamedRequestParameter.java
(original)
+++
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/NamedRequestParameter.java
Mon Feb 17 09:15:07 2014
@@ -22,6 +22,13 @@ import org.apache.sling.api.request.Requ
import aQute.bnd.annotation.ProviderType;
+/**
+ * The <code>NamedRequestParameter</code> interface extends the standard Sling
+ * API RequestParameter interface. Instances of this class are returned from
the
+ * {@link ParameterSupport#getRequestParameterList()} method.
+ * <p>
+ * This interface is not intended to be implemented by consumers
+ */
@ProviderType
public interface NamedRequestParameter extends RequestParameter {
Modified:
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/ParameterSupport.java
URL:
http://svn.apache.org/viewvc/sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/ParameterSupport.java?rev=1568913&r1=1568912&r2=1568913&view=diff
==============================================================================
---
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/ParameterSupport.java
(original)
+++
sling/whiteboard/fmeschbe/parameters/parameters/src/main/java/org/apache/sling/parameters/ParameterSupport.java
Mon Feb 17 09:15:07 2014
@@ -23,52 +23,108 @@ import java.util.Enumeration;
import java.util.List;
import java.util.Map;
-import javax.servlet.ServletRequest;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletRequestWrapper;
+import javax.servlet.http.Part;
import org.apache.sling.api.request.RequestParameter;
import org.apache.sling.api.request.RequestParameterMap;
+import
org.apache.sling.parameters.impl.ParameterSupportHttpServletRequestWrapper2x;
import
org.apache.sling.parameters.impl.ParameterSupportHttpServletRequestWrapper3;
import org.apache.sling.parameters.impl.ParameterSupportImpl;
-import org.apache.sling.parameters.impl.Util;
import aQute.bnd.annotation.ProviderType;
+/**
+ * The <code>ParameterSupport</code> class provides access to the Apache Sling
+ * request parameter support methods.
+ * <p>
+ * Orignally this was an internal piece of the Apache Sling Engine and has now
+ * been extracted and exported to allow servlets (and filters) outside of the
+ * Apache Sling Engine to benefit from Sling's support for request parameter
+ * parsing.
+ * <p>
+ * In addition to the Standard Servlet API 2.5 request parameter support this
+ * class provides:
+ * <ul>
+ * <li>Support for the Apache Sling {@code RequestParameter} API</li>
+ * <li>Support parsing {@code multipart/form-data} requests</li>
+ * <li>Support Servlet API 3.0 {@code Part} API in a Servlet API 3 context</li>
+ * <li>Guarantee parameter order in the {@link #getParameterMap()} and
+ * {@link #getParameterNames()} methods</li>
+ * <li>Provide a list of {@link NamedRequestParameter} instances in the order
as
+ * provided in the request</li>
+ * </ul>
+ * <p>
+ * This class is not expected to be implemented by consumers. Rather consumers
+ * are expected to use the static factory methods
+ * {@link #getInstance(HttpServletRequest)} or
+ * {@link #getParameterSupportRequestWrapper(HttpServletRequest)} to get an
+ * instance of this class.
+ *
+ * @see <a
+ *
href="http://sling.apache.org/documentation/the-sling-engine/request-parameters.html";>Request
+ * Parameter Handling in Sling</a>
+ */
@ProviderType
public abstract class ParameterSupport {
- /** The name of the form encoding parameter */
+ /**
+ * The name of the form encoding request parameter indicating the character
+ * encoding of submitted request parameters. This request parameter
+ * overwrites any value of the {@code
ServletRequest.getCharacterEncoding()}
+ * method (which unfortunately happens to be returning {@code null} most of
+ * the time.
+ */
public final static String PARAMETER_FORMENCODING = "_charset_";
+ // name of the request attribute caching the ParameterSupport instance
+ // used during the request
private static final String ATTR_NAME =
ParameterSupportImpl.class.getName();
- public static ParameterSupport getInstance(ServletRequest servletRequest) {
- Object instance = servletRequest.getAttribute(ATTR_NAME);
+ /**
+ * Returns the {@code ParameterSupport} instance supporting request
+ * parameter for the give {@code request}. For a single request only a
+ * single instance is actually used. This single instance is cached as a
+ * request attribute. If such an attribute already exists which is not an
+ * instance of this class, the request parameter is replaced.
+ *
+ * @param request The {@code HttpServletRequest} for which to return
request
+ * parameter support.
+ * @return The {@code ParameterSupport} for the given request.
+ */
+ public static ParameterSupport getInstance(HttpServletRequest request) {
+ Object instance = request.getAttribute(ATTR_NAME);
if (!(instance instanceof ParameterSupport)) {
- instance = new ParameterSupportImpl((HttpServletRequest)
servletRequest);
- servletRequest.setAttribute(ATTR_NAME, instance);
+ instance = new ParameterSupportImpl(request);
+ request.setAttribute(ATTR_NAME, instance);
}
return (ParameterSupport) instance;
}
/**
- * Sets the default encoding used to decode request parameters if the
- * <code>_charset_</code> request parameter is not set (or is not set to an
- * encoding supported by the platform). By default this default encoding is
- * <code>ISO-8859-1</code>. For applications which alway use the same
- * encoding this default can be changed.
- *
- * @param encoding The default encoding to be used. If this encoding is
- * <code>null</code> or not supported by the platform the
current
- * default encoding remains unchanged.
+ * Returns a {@code HttpServletRequestWrapper} which implements request
+ * parameter access backed by an instance of the {@code ParameterSupport}
+ * class.
+ * <p>
+ * If used in a Servlet API 3 context, this method supports the additional
+ * {@code Part} API introduced with Servlet API 3.
+ *
+ * @param request The {@code HttpServletRequest} to wrap
+ * @return The wrapped {@code request}
*/
- public static void setDefaultParameterEncoding(final String encoding) {
- Util.setDefaultFixEncoding(encoding);
- }
-
public static HttpServletRequestWrapper
getParameterSupportRequestWrapper(final HttpServletRequest request) {
- return new ParameterSupportHttpServletRequestWrapper3(request);
+
+ try {
+ if (request.getClass().getMethod("getServletContext") != null) {
+ return new ParameterSupportHttpServletRequestWrapper3(request);
+ }
+ } catch (Exception e) {
+ // If the getServletContext method does not exist or
+ // is not visible, fall back to a Servlet API 2.x wrapper
+ }
+
+ return new ParameterSupportHttpServletRequestWrapper2x(request);
}
/**
@@ -76,24 +132,168 @@ public abstract class ParameterSupport {
*/
public abstract boolean requestDataUsed();
+ /**
+ * Returns the value of a request parameter as a <code>String</code>, or
+ * <code>null</code> if the parameter does not exist. Request parameters
are
+ * extra information sent with the request. For HTTP servlets, parameters
+ * are contained in the query string or posted form data.
+ * <p>
+ * You should only use this method when you are sure the parameter has only
+ * one value. If the parameter might have more than one value, use
+ * {@link #getParameterValues}.
+ * <p>
+ * If you use this method with a multivalued parameter, the value returned
+ * is equal to the first value in the array returned by
+ * <code>getParameterValues</code>.
+ * <p>
+ * If the parameter data was sent in the request body, such as occurs with
+ * an HTTP POST request, then reading the body directly can interfere with
+ * the execution of this method.
+ *
+ * @param name a <code>String</code> specifying the name of the parameter
+ * @return a <code>String</code> representing the single value of the
+ * parameter
+ * @see #getParameterValues
+ */
public abstract String getParameter(String name);
+ /**
+ * Returns an array of <code>String</code> objects containing all of the
+ * values the given request parameter has, or <code>null</code> if the
+ * parameter does not exist.
+ * <p>
+ * If the parameter has a single value, the array has a length of 1.
+ *
+ * @param name a <code>String</code> containing the name of the parameter
+ * whose value is requested
+ * @return an array of <code>String</code> objects containing the
+ * parameter's values
+ * @see #getParameter
+ */
public abstract String[] getParameterValues(String name);
+ /**
+ * Returns a java.util.Map of the parameters of this request.
+ * <p>
+ * Request parameters are extra information sent with the request. For HTTP
+ * servlets, parameters are contained in the query string or posted form
+ * data.
+ *
+ * @return an immutable java.util.Map containing parameter names as keys
and
+ * parameter values as map values. The keys in the parameter map
are
+ * of type String. The values in the parameter map are of type
+ * String array.
+ */
public abstract Map<String, String[]> getParameterMap();
+ /**
+ * Returns an <code>Enumeration</code> of <code>String</code> objects
+ * containing the names of the parameters contained in this request. If the
+ * request has no parameters, the method returns an empty
+ * <code>Enumeration</code>.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code> objects, each
+ * <code>String</code> containing the name of a request parameter;
+ * or an empty <code>Enumeration</code> if the request has no
+ * parameters
+ */
public abstract Enumeration<String> getParameterNames();
+ /**
+ * Returns the value of a request parameter as a {@link RequestParameter},
+ * or <code>null</code> if the parameter does not exist.
+ * <p>
+ * This method should only be used if the parameter has only one value. If
+ * the parameter might have more than one value, use
+ * {@link #getRequestParameters(String)}.
+ * <p>
+ * If this method is used with a multivalued parameter, the value returned
+ * is equal to the first value in the array returned by
+ * <code>getRequestParameters</code>.
+ * <p>
+ * This method is a shortcut for
+ * <code>getRequestParameterMap().getValue(String)</code>.
+ *
+ * @param name a <code>String</code> specifying the name of the parameter
+ * @return a {@link RequestParameter} representing the single value of the
+ * parameter
+ * @see #getRequestParameters(String)
+ * @see RequestParameterMap#getValue(String)
+ * @throws IllegalArgumentException if name is <code>null</code>.
+ */
public abstract RequestParameter getRequestParameter(String name);
+ /**
+ * Returns an array of {@link RequestParameter} objects containing all of
+ * the values the given request parameter has, or <code>null</code> if the
+ * parameter does not exist.
+ * <p>
+ * If the parameter has a single value, the array has a length of 1.
+ * <p>
+ * This method is a shortcut for
+ * <code>getRequestParameterMap().getValues(String)</code>.
+ *
+ * @param name a <code>String</code> containing the name of the parameter
+ * the value of which is requested
+ * @return an array of {@link RequestParameter} objects containing the
+ * parameter values.
+ * @see #getRequestParameter(String)
+ * @see RequestParameterMap#getValues(String)
+ * @throws IllegalArgumentException if name is <code>null</code>.
+ */
public abstract RequestParameter[] getRequestParameters(String name);
+ /**
+ * Returns a <code>Map</code> of the parameters of this request.
+ * <p>
+ * The values in the returned <code>Map</code> are from type
+ * {@link RequestParameter} array (<code>RequestParameter[]</code>).
+ * <p>
+ * If no parameters exist this method returns an empty <code>Map</code>.
+ *
+ * @return an immutable <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
+ * {@link RequestParameter} array
(<code>RequestParameter[]</code>).
+ */
+ public abstract RequestParameterMap getRequestParameterMap();
+
+ /**
+ * Gets the {@link Part} with the given name.
+ *
+ * @param name the name of the requested Part
+ * @return The Part with the given name, or <tt>null</tt> if this request
is
+ * of type <tt>multipart/form-data</tt>, but does not contain the
+ * requested Part
+ */
public abstract Object getPart(String name);
+ /**
+ * Gets all the {@link Part} components of this request, provided that it
is
+ * of type <tt>multipart/form-data</tt>.
+ * <p>
+ * If this request is of type <tt>multipart/form-data</tt>, but does not
+ * contain any Part components, the returned <tt>Collection</tt> will be
+ * empty.
+ * <p>
+ * Any changes to the returned <code>Collection</code> must not affect this
+ * <code>HttpServletRequest</code>.
+ *
+ * @return a (possibly empty) <code>Collection</code> of the Part
components
+ * of this request
+ */
public abstract Collection<?> getParts();
- public abstract RequestParameterMap getRequestParameterMap();
-
+ /**
+ * Returns the request parameters as instances of the
+ * {@link NamedRequestParameter} interface in the order or the request
where
+ * the query string parameters are first and the POST request parameters
are
+ * second.
+ *
+ * @return The list of {@link NamedRequestParameter} in request declaration
+ * order.
+ */
public abstract List<NamedRequestParameter> getRequestParameterList();
}
\ No newline at end of file
