Assorted javadoc updates. Add more explicit error conditions often assocaited with passing null, require IllegalArgument/IlleglStateExceptions to be thrown. svn path=/trunk/; revision=486
diff --git a/src/jsr311-api/src/javax/ws/rs/Consumes.java b/src/jsr311-api/src/javax/ws/rs/Consumes.java index c8ed9e8..fe74d6a 100644 --- a/src/jsr311-api/src/javax/ws/rs/Consumes.java +++ b/src/jsr311-api/src/javax/ws/rs/Consumes.java
@@ -26,8 +26,8 @@ import java.lang.annotation.Target; /** - * Defines the media types that the methods of a resource class or MessageBodyReader - * can accept. If + * Defines the media types that the methods of a resource class or + * {@link javax.ws.rs.ext.MessageBodyReader} can accept. If * not specified, a container will assume that any media type is acceptable. * Method level annotations override a class level annotation. A container * is responsible for ensuring that the method invoked is capable of consuming
diff --git a/src/jsr311-api/src/javax/ws/rs/FormParam.java b/src/jsr311-api/src/javax/ws/rs/FormParam.java index 0da56a2..00f8b0b 100644 --- a/src/jsr311-api/src/javax/ws/rs/FormParam.java +++ b/src/jsr311-api/src/javax/ws/rs/FormParam.java
@@ -29,8 +29,8 @@ * 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. + * If the request entity body is absent or is an unsupported media type, the + * default value is used. * * The type <code>T</code> of the annotated parameter must either: * <ol>
diff --git a/src/jsr311-api/src/javax/ws/rs/Produces.java b/src/jsr311-api/src/javax/ws/rs/Produces.java index cdb10fc..9e68ab8 100644 --- a/src/jsr311-api/src/javax/ws/rs/Produces.java +++ b/src/jsr311-api/src/javax/ws/rs/Produces.java
@@ -27,7 +27,7 @@ /** * Defines the media type(s) that the methods of a resource class or - * MessageBodyWriter can produce. + * {@link javax.ws.rs.ext.MessageBodyWriter} can produce. * If not specified then a container will assume that any type can be produced. * Method level annotations override a class level annotation. A container * is responsible for ensuring that the method invoked is capable of producing
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Application.java b/src/jsr311-api/src/javax/ws/rs/core/Application.java index 55368f4..b03f1d7 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/Application.java +++ b/src/jsr311-api/src/javax/ws/rs/core/Application.java
@@ -32,25 +32,29 @@ * <p>Implementations should warn about and ignore classes that do not * conform to the requirements of root resource or provider classes. * Implementations should warn about and ignore classes for which - * {@link #getSingletons()} returns an instance.</p> + * {@link #getSingletons()} returns an instance. Implementations MUST + * NOT modify the returned set.</p> * - * @return a set of root resource and provider classes. + * @return a set of root resource and provider classes. Returning null + * is equivalent to returning an empty set. */ public abstract Set<Class<?>> getClasses(); /** * Get a set of root resource and provider instances. Fields and properties * of returned instances are injected with their declared dependencies - * (see {@link Context}) prior to use. + * (see {@link Context}) by the runtime prior to use. * * <p>Implementations should warn about and ignore classes that do not * conform to the requirements of root resource or provider classes. * Implementations should flag an error if the returned set includes - * more than one instance of the same class.</p> + * more than one instance of the same class. Implementations MUST + * NOT modify the returned set.</p> * * <p>The default implementation returns an empty set.</p> * - * @return a set of root resource and provider instances. + * @return a set of root resource and provider instances. Returning null + * is equivalent to returning an empty set. */ public Set<Object> getSingletons() { return emptySet;
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Cookie.java b/src/jsr311-api/src/javax/ws/rs/core/Cookie.java index b0fd887..4b8742e 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/Cookie.java +++ b/src/jsr311-api/src/javax/ws/rs/core/Cookie.java
@@ -163,7 +163,7 @@ /** * Compare for equality - * @param obj + * @param obj the object to compare to * @return true if the object is a {@code Cookie} with the same value for * all properties, false otherwise. */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/MediaType.java b/src/jsr311-api/src/javax/ws/rs/core/MediaType.java index ca2328b..e25ef0f 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/MediaType.java +++ b/src/jsr311-api/src/javax/ws/rs/core/MediaType.java
@@ -83,6 +83,11 @@ /** "application/x-www-form-urlencoded" */ public final static MediaType APPLICATION_FORM_URLENCODED_TYPE = new MediaType("application","x-www-form-urlencoded"); + /** "multipart/form-data" */ + public final static String MULTIPART_FORM_DATA = "multipart/form-data"; + /** "multipart/form-data" */ + public final static MediaType MULTIPART_FORM_DATA_TYPE = new MediaType("multipart","form-data"); + /** "application/octet-stream" */ public final static String APPLICATION_OCTET_STREAM = "application/octet-stream"; /** "application/octet-stream" */ @@ -117,9 +122,12 @@ /** * Creates a new instance of MediaType with the supplied type, subtype and * parameters. - * @param type the primary type - * @param subtype the subtype - * @param parameters a map of media type parameters + * @param type the primary type, null is equivalent to + * {@link #MEDIA_TYPE_WILDCARD}. + * @param subtype the subtype, null is equivalent to + * {@link #MEDIA_TYPE_WILDCARD}. + * @param parameters a map of media type parameters, null is the same as an + * empty map. */ public MediaType(String type, String subtype, Map<String, String> parameters) { this.type = type==null ? MEDIA_TYPE_WILDCARD : type; @@ -141,8 +149,10 @@ /** * Creates a new instance of MediaType with the supplied type and subtype. - * @param type the primary type - * @param subtype the subtype + * @param type the primary type, null is equivalent to + * {@link #MEDIA_TYPE_WILDCARD} + * @param subtype the subtype, null is equivalent to + * {@link #MEDIA_TYPE_WILDCARD} */ public MediaType(String type, String subtype) { this(type,subtype,emptyMap);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java b/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java index 90d9621..83ede1e 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java +++ b/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java
@@ -90,6 +90,7 @@ /** * Create a new instance copying the information in the supplied cookie. * @param cookie the cookie to clone + * @throws IllegalArgumentException if cookie is null */ public NewCookie(Cookie cookie) { super(cookie.getName(), cookie.getValue(), cookie.getPath(), cookie.getDomain(), cookie.getVersion()); @@ -101,6 +102,7 @@ * @param comment the comment * @param maxAge the maximum age of the cookie in seconds * @param secure specifies whether the cookie will only be sent over a secure connection + * @throws IllegalArgumentException if cookie is null */ public NewCookie(Cookie cookie, String comment, int maxAge, boolean secure) { this(cookie.getName(), cookie.getValue(), cookie.getPath(), cookie.getDomain(), cookie.getVersion(), comment, maxAge, secure);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Request.java b/src/jsr311-api/src/javax/ws/rs/core/Request.java index 4c02702..e17fa0f 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/Request.java +++ b/src/jsr311-api/src/javax/ws/rs/core/Request.java
@@ -60,7 +60,7 @@ * available representation variants. * @return the variant that best matches the request. * @see Variant.VariantListBuilder - * @throws IllegalArgumentException if variants is empty + * @throws java.lan.IllegalArgumentException if variants is empty or null * @throws java.lang.IllegalStateException if called outside the scope of a request */ Variant selectVariant(List<Variant> variants) throws IllegalArgumentException; @@ -72,6 +72,7 @@ * @return null if the preconditions are met or a ResponseBuilder set with * the appropriate status if the preconditions are not met. A returned * ResponseBuilder will include an ETag header set with the value of eTag. + * @throws java.lang.IllegalArgumentException if eTag is null * @throws java.lang.IllegalStateException if called outside the scope of a request */ ResponseBuilder evaluatePreconditions(EntityTag eTag); @@ -82,6 +83,7 @@ * @param lastModified a date that specifies the modification date of the resource * @return null if the preconditions are met or a ResponseBuilder set with * the appropriate status if the preconditions are not met. + * @throws java.lang.IllegalArgumentException if lastModified is null * @throws java.lang.IllegalStateException if called outside the scope of a request */ ResponseBuilder evaluatePreconditions(Date lastModified); @@ -94,6 +96,7 @@ * @return null if the preconditions are met or a ResponseBuilder set with * the appropriate status if the preconditions are not met. A returned * ResponseBuilder will include an ETag header set with the value of eTag. + * @throws java.lang.IllegalArgumentException if lastModified or eTag is null * @throws java.lang.IllegalStateException if called outside the scope of a request */ ResponseBuilder evaluatePreconditions(Date lastModified, EntityTag eTag);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Response.java b/src/jsr311-api/src/javax/ws/rs/core/Response.java index 1d875bb..2ba60b1 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/Response.java +++ b/src/jsr311-api/src/javax/ws/rs/core/Response.java
@@ -57,7 +57,7 @@ /** * Get the status code associated with the response. - * @return the response status code or -1 if the status was not set + * @return the response status code or -1 if the status was not set. */ public abstract int getStatus(); @@ -110,6 +110,8 @@ * Create a new ResponseBuilder with the supplied status. * @param status the response status * @return a new ResponseBuilder + * @throws IllegalArgumentException if status is less than 100 or greater + * than 599. */ public static ResponseBuilder status(int status) { ResponseBuilder b = ResponseBuilder.newInstance(); @@ -128,9 +130,9 @@ } /** - * Create a new ResponseBuilder that contains a representation. Wrap the - * actual entity with {@link GenericEntity} if the generic type should be - * preserved. + * Create a new ResponseBuilder that contains a representation. It is the + * callers responsibility to wrap the actual entity with + * {@link GenericEntity} if preservation of its generic type is required. * * @param entity the representation entity data * @return a new ResponseBuilder @@ -142,9 +144,9 @@ } /** - * Create a new ResponseBuilder that contains a representation. If - * required, wrap the actual entity with {@link GenericEntity} to preserve - * the generic type. + * Create a new ResponseBuilder that contains a representation. It is the + * callers responsibility to wrap the actual entity with + * {@link GenericEntity} if preservation of its generic type is required. * * @param entity the representation entity data * @param type the media type of the entity @@ -158,9 +160,9 @@ } /** - * Create a new ResponseBuilder that contains a representation. If - * required, wrap the actual entity with {@link GenericEntity} to preserve - * the generic type. + * Create a new ResponseBuilder that contains a representation. It is the + * callers responsibility to wrap the actual entity with + * {@link GenericEntity} if preservation of its generic type is required. * * @param entity the representation entity data * @param type the media type of the entity @@ -174,9 +176,9 @@ } /** - * Create a new ResponseBuilder that contains a representation. If - * required, wrap the actual entity with {@link GenericEntity} to preserve - * the generic type. + * Create a new ResponseBuilder that contains a representation. It is the + * callers responsibility to wrap the actual entity with + * {@link GenericEntity} if preservation of its generic type is required. * * @param entity the representation entity data * @param variant representation metadata @@ -207,6 +209,7 @@ * supplied it will be converted into an absolute URI by resolving it * relative to the request URI (see {@link UriInfo#getRequestUri}). * @return a new ResponseBuilder + * @throws java.lang.IllegalArgumentException if location is null */ public static ResponseBuilder created(URI location) { ResponseBuilder b = status(Status.CREATED).location(location); @@ -238,6 +241,7 @@ * * @param tag a tag for the unmodified entity * @return a new ResponseBuilder + * @throws java.lang.IllegalArgumentException if tag is null */ public static ResponseBuilder notModified(EntityTag tag) { ResponseBuilder b = notModified(); @@ -253,6 +257,7 @@ * @param tag the string content of a strong entity tag. The JAX-RS * runtime will quote the supplied value when creating the header. * @return a new ResponseBuilder + * @throws java.lang.IllegalArgumentException if tag is null */ public static ResponseBuilder notModified(String tag) { ResponseBuilder b = notModified(); @@ -269,6 +274,7 @@ * relative to the base URI of the application (see * {@link UriInfo#getBaseUri}). * @return a new ResponseBuilder + * @throws java.lang.IllegalArgumentException if location is null */ public static ResponseBuilder seeOther(URI location) { ResponseBuilder b = status(Status.SEE_OTHER).location(location); @@ -283,6 +289,7 @@ * relative to the base URI of the application (see * {@link UriInfo#getBaseUri}). * @return a new ResponseBuilder + * @throws java.lang.IllegalArgumentException if location is null */ public static ResponseBuilder temporaryRedirect(URI location) { ResponseBuilder b = status(Status.TEMPORARY_REDIRECT).location(location); @@ -292,7 +299,8 @@ /** * Create a new ResponseBuilder for a not acceptable response. * - * @param variants list of variants that were available + * @param variants list of variants that were available, a null vaue is + * equivalent to an empty list. * @return a new ResponseBuilder */ public static ResponseBuilder notAcceptable(List<Variant> variants) { @@ -359,6 +367,8 @@ * * @param status the response status * @return the updated ResponseBuilder + * @throws IllegalArgumentException if status is less than 100 or greater + * than 599. */ public abstract ResponseBuilder status(int status); @@ -376,8 +386,9 @@ }; /** - * Set the entity on the ResponseBuilder. If required, wrap the actual - * entity with {@link GenericEntity} to preserve the generic type. + * Set the entity on the ResponseBuilder. It is the + * callers responsibility to wrap the actual entity with + * {@link GenericEntity} if preservation of its generic type is required. * * @param entity the response entity * @return the updated ResponseBuilder @@ -405,8 +416,8 @@ /** * Set representation metadata on the ResponseBuilder. * - * - * @param variant metadata of the response entity + * @param variant metadata of the response entity a null value is + * equivalent to a variant with all null properties * @return the updated ResponseBuilder */ public abstract ResponseBuilder variant(Variant variant); @@ -414,7 +425,8 @@ /** * Add a Vary header that lists the available variants. * - * @param variants a list of available representation variants + * @param variants a list of available representation variants, a null + * value is equivalent to an empty list. * @return the updated ResponseBuilder */ public abstract ResponseBuilder variants(List<Variant> variants); @@ -422,7 +434,6 @@ /** * Set the language on the ResponseBuilder. * - * * @param language the language of the response entity * @return the updated ResponseBuilder */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java b/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java index e9c2dd6..55ce194 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java +++ b/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java
@@ -39,7 +39,7 @@ * @throws java.io.IOException if an IO error is encountered * @throws javax.ws.rs.WebApplicationException if a specific * HTTP error response needs to be produced. Only effective if thrown prior - * to the response being committed. + * to any bytes being written to output. */ void write(OutputStream output) throws IOException, WebApplicationException; }
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 e17a3b1..f9227a2 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java +++ b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
@@ -86,8 +86,7 @@ public List<PathSegment> getPathSegments(boolean decode); /** - * Get the absolute request URI. This includes query parameters and - * any supplied fragment. + * Get the absolute request URI including any query parameters. * @return the absolute request URI * @throws java.lang.IllegalStateException if called outside the scope of a request */ @@ -102,7 +101,7 @@ /** * Get the absolute path of the request. This includes everything preceding - * the path (host, port etc) but excludes query parameters and fragment. + * the path (host, port etc) but excludes query parameters. * This is a shortcut for * <code>uriInfo.getBase().resolve(uriInfo.getPath()).</code> * @return the absolute path of the request @@ -113,7 +112,7 @@ /** * Get the absolute path of the request in the form of a UriBuilder. * This includes everything preceding the path (host, port etc) but excludes - * query parameters and fragment. + * query parameters. * @return a UriBuilder initialized with the absolute path of the request * @throws java.lang.IllegalStateException if called outside the scope of a request */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Variant.java b/src/jsr311-api/src/javax/ws/rs/core/Variant.java index 4e7f27b..b8df85c 100644 --- a/src/jsr311-api/src/javax/ws/rs/core/Variant.java +++ b/src/jsr311-api/src/javax/ws/rs/core/Variant.java
@@ -38,6 +38,8 @@ * @param mediaType the media type of the variant - may be null * @param language the language of the variant - may be null * @param encoding the content encoding of the variant - may be null + * @throws java.lang.IllegalArgumentException if all three parameters are + * null */ public Variant(MediaType mediaType, Locale language, String encoding) { this.encoding = encoding; @@ -76,6 +78,8 @@ * are supported they should be included as parameters of the respective * media type. * @return the initailized builder + * @throws java.lang.IllegalArgumentException if mediaTypes is null or + * contains no elements. */ public static VariantListBuilder mediaTypes(MediaType... mediaTypes) { VariantListBuilder b = VariantListBuilder.newInstance(); @@ -88,6 +92,8 @@ * languages. * @param languages the available languages. * @return the initailized builder + * @throws java.lang.IllegalArgumentException if languages is null or + * contains no elements. */ public static VariantListBuilder languages(Locale... languages) { VariantListBuilder b = VariantListBuilder.newInstance(); @@ -100,6 +106,8 @@ * encodings. * @param encodings the available encodings. * @return the initailized builder + * @throws java.lang.IllegalArgumentException if encodings is null or + * contains no elements. */ public static VariantListBuilder encodings(String... encodings) { VariantListBuilder b = VariantListBuilder.newInstance(); @@ -197,8 +205,9 @@ * <p><pre>List<Variant> list = VariantListBuilder.newInstance().languages("en","fr") * .encodings("zip", "identity").add().build()</pre> * - * * @return the updated builder + * @throws java.lang.IllegalStateException if there is not at least one + * mediaType, language or encoding set for the current variant. */ public abstract VariantListBuilder add();
diff --git a/src/jsr311-api/src/javax/ws/rs/ext/Providers.java b/src/jsr311-api/src/javax/ws/rs/ext/Providers.java index d553fd8..ef2a51d 100644 --- a/src/jsr311-api/src/javax/ws/rs/ext/Providers.java +++ b/src/jsr311-api/src/javax/ws/rs/ext/Providers.java
@@ -38,9 +38,9 @@ * Get a message body reader that matches a set of criteria. The set of * readers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each reader's - * {@link javax.ws.rs.Consumes}, comparing the supplied value of - * {@code type} with the generic type of the reader, and eliminating those - * that do not match. + * {@link javax.ws.rs.Consumes}, ensuring the supplied value of + * {@code type} is assignable to the generic type of the reader, and + * eliminating those that do not match. * The list of matching readers is then ordered with those with the best * matching values of {@link javax.ws.rs.Consumes} (x/y > x/* > */*) * sorted first. Finally, the @@ -48,6 +48,7 @@ * method is called on each reader in order using the supplied criteria and * the first reader that returns {@code true} is selected and returned. * + * @param type the class of object that is to be written. * @param mediaType the media type of the data that will be read. * @param genericType the type of object to be produced. E.g. if the * message body is to be converted into a method parameter, this will be @@ -68,9 +69,9 @@ * Get a message body writer that matches a set of criteria. The set of * writers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each writer's - * {@link javax.ws.rs.Produces}, comparing the supplied value of - * {@code type} with the generic type of the writer, and eliminating those - * that do not match. + * {@link javax.ws.rs.Produces}, ensuring the supplied value of + * {@code type} is assignable to the generic type of the reader, and + * eliminating those that do not match. * The list of matching writers is then ordered with those with the best * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) * sorted first. Finally, the @@ -109,11 +110,11 @@ * Get a context resolver for a particular type of context and media type. * The set of resolvers is first filtered by comparing the supplied value of * {@code mediaType} with the value of each resolver's - * {@link javax.ws.rs.Produces}, comparing the supplied value of - * {@code type} with the generic type of the resolver, and eliminating those - * that do not match. If only one resolver matches the criteria then it is - * returned. If more than one resolver matches then the list of matching - * resolvers is ordered with those with the best + * {@link javax.ws.rs.Produces}, ensuring the generic type of the context + * resolver is assignable to the supplied value of {@code contextType}, and + * eliminating those that do not match. If only one resolver matches the + * criteria then it is returned. If more than one resolver matches then the + * list of matching resolvers is ordered with those with the best * matching values of {@link javax.ws.rs.Produces} (x/y > x/* > */*) * sorted first. A proxy is returned that delegates calls to * {@link ContextResolver#getContext(java.lang.Class)} to each matching context
diff --git a/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java b/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java index cbf5511..7ee70dc 100644 --- a/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java +++ b/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java
@@ -133,8 +133,7 @@ } /** - * Create a new instance of a {@link javax.ws.rs.core.UriBuilder} with - * automatic encoding enabled. + * Create a new instance of a {@link javax.ws.rs.core.UriBuilder}. * @return new UriBuilder instance * @see javax.ws.rs.core.UriBuilder */ @@ -162,8 +161,8 @@ * @param application the application configuration * @param endpointType the type of endpoint instance to be created. * @return a configured instance of the requested type. - * @throws java.lang.IllegalArgumentException if the requested endpoint - * type is not supported. + * @throws java.lang.IllegalArgumentException if application is null or the + * requested endpoint type is not supported. * @throws java.lang.UnsupportedOperationException if the implementation * supports no endpoint types. */ @@ -173,9 +172,12 @@ /** * Obtain an instance of a HeaderDelegate for the supplied class. An * implementation is required to support the following values for type: - * Cookie, CacheControl, EntityTag, NewCookie, MediaType, Date. + * {@link javax.ws.rs.core.Cookie}, {@link javax.ws.rs.core.CacheControl}, + * {@link javax.ws.rs.core.EntityTag}, {@link javax.ws.rs.core.NewCookie}, + * {@link javax.ws.rs.core.MediaType} and {@code java.util.Date}. * @param type the class of the header * @return an instance of HeaderDelegate for the supplied type + * @throws java.lang.IllegalArgumentException if type is null */ public abstract <T> HeaderDelegate<T> createHeaderDelegate(Class<T> type);