Update Javadoc to reflect that query, matrix and form param names are always decoded.
svn path=/trunk/; revision=508
diff --git a/src/jsr311-api/src/javax/ws/rs/Encoded.java b/src/jsr311-api/src/javax/ws/rs/Encoded.java
index 8a348eb..965c019 100644
--- a/src/jsr311-api/src/javax/ws/rs/Encoded.java
+++ b/src/jsr311-api/src/javax/ws/rs/Encoded.java
@@ -26,10 +26,8 @@
import java.lang.annotation.Target;
/**
- * Disables automatic decoding of values bound using either {@link QueryParam},
- * {@link PathParam}, {@link FormParam} or {@link MatrixParam}. This annotation
- * is only effective when combined with one of these annotations, implementations
- * should warn if the annotation is used on a scope where it will have no effect.
+ * Disables automatic decoding of parameter values bound using {@link QueryParam},
+ * {@link PathParam}, {@link FormParam} or {@link MatrixParam}.
* Using this annotation on a method will disable decoding for all parameters.
* Using this annotation on a class will disable decoding for all parameters of
* all methods.
diff --git a/src/jsr311-api/src/javax/ws/rs/FormParam.java b/src/jsr311-api/src/javax/ws/rs/FormParam.java
index 00f8b0b..a5aa84a 100644
--- a/src/jsr311-api/src/javax/ws/rs/FormParam.java
+++ b/src/jsr311-api/src/javax/ws/rs/FormParam.java
@@ -58,11 +58,11 @@
public @interface FormParam {
/**
* Defines the name of the form parameter whose value will be used
- * to initialize the value of the annotated method argument.
- *
- * <p>The supplied value is automatically percent encoded. Note that percent
- * encoded values are allowed in the value, an implementation will recognize
- * such values and will not double encode the '%' character.</p>
+ * to initialize the value of the annotated method argument. The name is
+ * specified in decoded form, any percent encoded literals within the value
+ * will not be decoded and will instead be treated as literal text. E.g. if
+ * the parameter name is "a b" then the value of the annotation is "a b",
+ * <i>not</i> "a+b" or "a%20b".
*/
String value();
}
diff --git a/src/jsr311-api/src/javax/ws/rs/MatrixParam.java b/src/jsr311-api/src/javax/ws/rs/MatrixParam.java
index fdf89c2..61f5f6e 100644
--- a/src/jsr311-api/src/javax/ws/rs/MatrixParam.java
+++ b/src/jsr311-api/src/javax/ws/rs/MatrixParam.java
@@ -62,11 +62,10 @@
/**
* Defines the name of the URI matrix parameter whose value will be used
* to initialize the value of the annotated method argument, class field or
- * bean property.
- *
- * <p>The supplied value is automatically percent encoded. Note that percent
- * encoded values are allowed in the value, an implementation will recognize
- * such values and will not double encode the '%' character.</p>
+ * bean property. The name is specified in decoded form, any percent encoded
+ * literals within the value will not be decoded and will instead be
+ * treated as literal text. E.g. if the parameter name is "a b" then the
+ * value of the annotation is "a b", <i>not</i> "a+b" or "a%20b".
*/
String value();
}
diff --git a/src/jsr311-api/src/javax/ws/rs/QueryParam.java b/src/jsr311-api/src/javax/ws/rs/QueryParam.java
index fc86a22..1cee16f 100644
--- a/src/jsr311-api/src/javax/ws/rs/QueryParam.java
+++ b/src/jsr311-api/src/javax/ws/rs/QueryParam.java
@@ -62,11 +62,10 @@
/**
* Defines the name of the HTTP query parameter whose value will be used
* to initialize the value of the annotated method argument, class field or
- * bean property.
- *
- * <p>The supplied value is automatically percent encoded. Note that percent
- * encoded values are allowed in the value, an implementation will recognize
- * such values and will not double encode the '%' character.</p>
+ * bean property. The name is specified in decoded form, any percent encoded
+ * literals within the value will not be decoded and will instead be
+ * treated as literal text. E.g. if the parameter name is "a b" then the
+ * value of the annotation is "a b", <i>not</i> "a+b" or "a%20b".
*/
String value();
}
diff --git a/src/jsr311-api/src/javax/ws/rs/core/PathSegment.java b/src/jsr311-api/src/javax/ws/rs/core/PathSegment.java
index 6d75855..5245ce1 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/PathSegment.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/PathSegment.java
@@ -24,7 +24,7 @@
* instance of this type is injected with {@link javax.ws.rs.PathParam}, the
* value of the annotation identifies which path segment is selected and the
* presence of an {@link javax.ws.rs.Encoded} annotation will result in an
- * instance that supplies the path and matrix parameters (names and values) in
+ * instance that supplies the path and matrix parameter values in
* URI encoded form.
*
* @see UriInfo#getPathSegments
@@ -38,8 +38,12 @@
* @return the path segment
*/
String getPath();
+
/**
- * Get a map of the matrix parameters associated with the path segment
+ * Get a map of the matrix parameters associated with the path segment.
+ * The map keys are the names of the matrix parameters with any
+ * percent-escaped octets decoded.
+ *
* @return the map of matrix parameters
* @see <a href="http://www.w3.org/DesignIssues/MatrixURIs.html">Matrix URIs</a>
*/
diff --git a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
index f9227a2..32393fe 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
@@ -60,7 +60,7 @@
* list of {@link PathSegment}. This method is useful when the
* path needs to be parsed, particularly when matrix parameters may be
* present in the path. All sequences of escaped octets in path segments
- * and matrix parmeter names and values are decoded,
+ * and matrix parameter values are decoded,
* equivalent to <code>getPathSegments(true)</code>.
* @return an unmodifiable list of {@link PathSegment}. The matrix parameter
* map of each path segment is also unmodifiable.
@@ -76,7 +76,7 @@
* path needs to be parsed, particularly when matrix parameters may be
* present in the path.
* @param decode controls whether sequences of escaped octets in path segments
- * and matrix parameter names and values are decoded (true) or not (false).
+ * and matrix parameter values are decoded (true) or not (false).
* @return an unmodifiable list of {@link PathSegment}. The matrix parameter
* map of each path segment is also unmodifiable.
* @throws java.lang.IllegalStateException if called outside the scope of a request
@@ -156,7 +156,9 @@
/**
* Get the URI query parameters of the current request.
- * All sequences of escaped octets in parameter names and values are decoded,
+ * The map keys are the names of the query parameters with any
+ * escaped characters decoded.
+ * All sequences of escaped octets in parameter values are decoded,
* equivalent to <code>getQueryParameters(true)</code>.
* @return an unmodifiable map of query parameter names and values
* @throws java.lang.IllegalStateException if called outside the scope of a request
@@ -165,8 +167,10 @@
/**
* Get the URI query parameters of the current request.
+ * The map keys are the names of the query parameters with any
+ * escaped characters decoded.
* @param decode controls whether sequences of escaped octets in parameter
- * names and values are decoded (true) or not (false).
+ * values are decoded (true) or not (false).
* @return an unmodifiable map of query parameter names and values
* @throws java.lang.IllegalStateException if called outside the scope of a request
*/
