Restrict use of FormParam to resource methods
svn path=/trunk/; revision=437
diff --git a/spec/chapters/annotations.tex b/spec/chapters/annotations.tex
index 8adb8a5..96d93fe 100644
--- a/spec/chapters/annotations.tex
+++ b/spec/chapters/annotations.tex
@@ -24,7 +24,7 @@
\hline
\code{QueryParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI query parameter. The value of the annotation identifies the name of a query parameter. \tabularnewline
\hline
-\code{FormParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a form parameter in a request entity body. The value of the annotation identifies the name of a form parameter. \tabularnewline
+\code{FormParam} & \raggedright Parameter & \raggedright Specifies that the value of a method parameter is to be extracted from a form parameter in a request entity body. The value of the annotation identifies the name of a form parameter. \tabularnewline
\hline
\code{MatrixParam} & \raggedright Parameter, field or method & \raggedright Specifies that the value of a method parameter, class field, or bean property is to be extracted from a URI matrix parameter. The value of the annotation identifies the name of a matrix parameter. \tabularnewline
\hline
@@ -34,7 +34,7 @@
\hline
\code{Encoded} & \raggedright Type, constructor, method, field or parameter & \raggedright Disables automatic URI decoding for path, query, form and matrix parameters. \tabularnewline
\hline
-\code{DefaultValue} & \raggedright Parameter, field or method & \raggedright Specifies a default value for a method parameter annotated with \QueryParam, \MatrixParam, \CookieParam, \FormParam\ or \HeaderParam. The specified value will be used if the corresponding query or matrix parameter is not present in the request URI, if the corresponding form parameter is not in the request entity body, or if the corresponding HTTP header is not included in the request.\tabularnewline
+\code{DefaultValue} & \raggedright Parameter, field or method & \raggedright Specifies a default value for a field, property or method parameter annotated with \QueryParam, \MatrixParam, \CookieParam, \FormParam\ or \HeaderParam. The specified value will be used if the corresponding query or matrix parameter is not present in the request URI, if the corresponding form parameter is not in the request entity body, or if the corresponding HTTP header is not included in the request.\tabularnewline
\hline
\code{Context} & \raggedright Field, method or parameter & \raggedright Identifies an injection target for one of the types listed in section \ref{contexttypes} or the applicable section of chapter \ref{environment}. \tabularnewline
\hline
diff --git a/spec/chapters/resources.tex b/spec/chapters/resources.tex
index 19a37bc..6d71832 100644
--- a/spec/chapters/resources.tex
+++ b/spec/chapters/resources.tex
@@ -31,7 +31,6 @@
\item[\MatrixParam] Extracts the value of a URI matrix parameter.
\item[\QueryParam] Extracts the value of a URI query parameter.
\item[\PathParam] Extracts the value of a URI template parameter.
-\item[\FormParam] Extracts the value of a form parameter contained within a request entity body.
\item[\CookieParam] Extracts the value of a cookie.
\item[\HeaderParam] Extracts the value of a header.
\item[\Context] Injects an instance of a supported resource, see chapters \ref{context} and \ref{environment} for more details.
@@ -50,9 +49,9 @@
\item \code{List<{\em T}>}, \code{Set<{\em T}>}, or \code{SortedSet<{\em T}>}, where \code{{\em T}} satisfies \ref{stringctor} or \ref{valueofmethod} above.
\end{enumerate}
-The \code{Default\-Value} annotation may be used to supply a default value for some of the above, see the Javadoc for \code{Default\-Value} for usage details and rules for generating a value in the absence of this annotation and the requested data. The \code{Encoded} annotation may be used to disable automatic URI decoding for \MatrixParam, \QueryParam, \FormParam\ and \PathParam\ annotated fields and properties.
+The \code{Default\-Value} annotation may be used to supply a default value for some of the above, see the Javadoc for \code{Default\-Value} for usage details and rules for generating a value in the absence of this annotation and the requested data. The \code{Encoded} annotation may be used to disable automatic URI decoding for \MatrixParam, \QueryParam, and \PathParam\ annotated fields and properties.
-A \WebAppExc\ thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above is processed directly as described in section \ref{method_exc}. Other exceptions thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above are treated as client errors: if the field or property is annotated with \MatrixParam, \QueryParam\ or \PathParam\ then an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a not found response (404 status) and no entity; if the field or property is annotated with \FormParam, \HeaderParam\ or \CookieParam\ then an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a client error response (400 status) and no entity. The \WebAppExc\ MUST be then be processed as described in section \ref{method_exc}.
+A \WebAppExc\ thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above is processed directly as described in section \ref{method_exc}. Other exceptions thrown during construction of field or property values using \ref{stringctor} or \ref{valueofmethod} above are treated as client errors: if the field or property is annotated with \MatrixParam, \QueryParam\ or \PathParam\ then an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a not found response (404 status) and no entity; if the field or property is annotated with \HeaderParam\ or \CookieParam\ then an implementation MUST generate a \WebAppExc\ that wraps the thrown exception with a client error response (400 status) and no entity. The \WebAppExc\ MUST be then be processed as described in section \ref{method_exc}.
\section{Resource Methods}
\label{resource_method}
@@ -68,7 +67,7 @@
\subsection{Parameters}
\label{resource_method_params}
-When a resource method is invoked, parameters annotated with one of the annotations listed in section \ref{resource_field} are mapped from the request according to the semantics of the annotation. Similarly for fields and bean properties:
+When a resource method is invoked, parameters annotated with \FormParam\ or one of the annotations listed in section \ref{resource_field} are mapped from the request according to the semantics of the annotation. Similar to fields and bean properties:
\begin{itemize}
\item The \code{Default\-Value} annotation may be used to supply a default value for parameters
\item The \code{Encoded} annotation may be used to disable automatic URI decoding of parameter values
diff --git a/src/jsr311-api/src/javax/ws/rs/FormParam.java b/src/jsr311-api/src/javax/ws/rs/FormParam.java
index ed59093..29638cd 100644
--- a/src/jsr311-api/src/javax/ws/rs/FormParam.java
+++ b/src/jsr311-api/src/javax/ws/rs/FormParam.java
@@ -26,15 +26,13 @@
/**
* Binds the value(s) of a form parameter contained within a request entity body
- * to a resource method parameter, resource class field, or resource class bean
- * property. Values are URL decoded unless this is disabled using the
- * {@link Encoded} annotation. A default value can be specified using the
- * {@link DefaultValue} annotation.
+ * to a resource method parameter. Values are URL decoded unless this is
+ * disabled using the {@link Encoded} annotation. A default value can be
+ * specified using the {@link DefaultValue} annotation.
* If the request entity body is absent or is of any media type other than
* application/x-www-form-urlencoded, the default value is used.
*
- * The type <code>T</code> of the annotated parameter, field or property must
- * either:
+ * The type <code>T</code> of the annotated parameter must either:
* <ol>
* <li>Be a primitive type</li>
* <li>Have a constructor that accepts a single <code>String</code> argument</li>
@@ -48,22 +46,15 @@
* <p>If the type is not one of those listed in 4 above then the first value
* (lexically) of the parameter is used.</p>
*
- * <p>Because injection occurs at object creation time, use of this annotation
- * on resource class fields and bean properties is only supported for the
- * default per-request resource class lifecycle. Resource classes using
- * other lifecycles should only use this annotation on resource method
- * parameters.</p>
- *
* @see DefaultValue
* @see Encoded
*/
-@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
+@Target({ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface FormParam {
/**
* Defines the name of the form parameter whose value will be used
- * to initialize the value of the annotated method argument, class field or
- * bean property.
+ * 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
