pax_global_header00006660000000000000000000000064113633424230014513gustar00rootroot0000000000000052 comment=aaccb37256fa4336a73ad38bde479d0b07af484c libjsr311-api-java-1.1.1/000077500000000000000000000000001136334242300147135ustar00rootroot00000000000000libjsr311-api-java-1.1.1/META-INF/000077500000000000000000000000001136334242300160535ustar00rootroot00000000000000libjsr311-api-java-1.1.1/META-INF/MANIFEST.MF000066400000000000000000000001561136334242300175070ustar00rootroot00000000000000Manifest-Version: 1.0 Archiver-Version: Plexus Archiver Created-By: 1.5.0_19-b02 (Sun Microsystems Inc.) libjsr311-api-java-1.1.1/javax/000077500000000000000000000000001136334242300160245ustar00rootroot00000000000000libjsr311-api-java-1.1.1/javax/ws/000077500000000000000000000000001136334242300164555ustar00rootroot00000000000000libjsr311-api-java-1.1.1/javax/ws/rs/000077500000000000000000000000001136334242300171015ustar00rootroot00000000000000libjsr311-api-java-1.1.1/javax/ws/rs/ApplicationPath.java000066400000000000000000000033401136334242300230240ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * ApplicationPath.java * * Created on August 21, 2009 * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Identifies the application path that serves as the base URI * for all resource URIs provided by {@link javax.ws.rs.Path}. May only be * applied to a subclass of {@link javax.ws.rs.core.Application}. * *

When published in a Servlet container, the value of the application path * may be overridden using a servlet-mapping element in the web.xml.

* * @see javax.ws.rs.core.Application * @see Path * @since 1.1 */ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface ApplicationPath { /** * Defines the base URI for all resource URIs. A trailing '/' character will * be automatically appended if one is not present. * *

The supplied value is automatically percent * encoded to conform to the {@code path} production of * {@link RFC 3986 section 3.3}. * Note that percent encoded values are allowed in the value, an * implementation will recognize such values and will not double * encode the '%' character.

*/ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/Consumes.java000066400000000000000000000033401136334242300215400ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Consumes.java * * Created on September 15, 2006, 2:40 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * 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 * the media type of the HTTP request entity body. If no such method is * available the container must respond with a HTTP "415 Unsupported Media Type" * as specified by RFC 2616. * * @see javax.ws.rs.ext.MessageBodyReader */ @Inherited @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface Consumes { /** * A list of media types. Each entry may specify a single type or consist * of a comma separated list of types. E.g. {"image/jpeg,image/gif", * "image/png"}. Use of the comma-separated form allows definition of a * common string constant for use on multiple targets. */ String[] value() default "*/*"; } libjsr311-api-java-1.1.1/javax/ws/rs/CookieParam.java000066400000000000000000000043631136334242300221440ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * CookieParam.java * * Created on November 16, 2006, 2:04 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value of a HTTP cookie to a resource method parameter, * resource class field, or resource class bean property. * A default value can be specified using the {@link DefaultValue} * annotation. * * The type T of the annotated parameter, field or property must * either: *
    *
  1. Be a primitive type
  2. *
  3. Be {@link javax.ws.rs.core.Cookie}
  4. *
  5. Have a constructor that accepts a single String argument
  6. *
  7. Have a static method named valueOf or fromString * that accepts a single * String argument (see, for example, {@link Integer#valueOf(String)}) *
  8. Be List<T>, Set<T> or * SortedSet<T>, where T satisfies 2, 3 or 4 above. * The resulting collection is read-only.
  9. *
* *

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.

* * @see DefaultValue * @see javax.ws.rs.core.Cookie * @see javax.ws.rs.core.HttpHeaders#getCookies */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface CookieParam { /** * Defines the name of the HTTP cookie whose value will be used * to initialize the value of the annotated method argument, class field or * bean property. */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/DELETE.java000066400000000000000000000015641136334242300207140ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * DELETE.java * * Created on October 24, 2007, 5:12 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP DELETE requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.DELETE) public @interface DELETE { } libjsr311-api-java-1.1.1/javax/ws/rs/DefaultValue.java000066400000000000000000000036231136334242300223310ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * DefaultValue.java * * Created on November 16, 2006, 2:04 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Defines the default value of request metadata that is bound using one of the * following annotations: * {@link javax.ws.rs.PathParam}, * {@link javax.ws.rs.QueryParam}, * {@link javax.ws.rs.MatrixParam}, * {@link javax.ws.rs.CookieParam}, * {@link javax.ws.rs.FormParam}, * or {@link javax.ws.rs.HeaderParam}. * The default value is used if the corresponding metadata is not present in the * request. * *

If the type of the annotated parameter is * List, Set or SortedSet then the * resulting collection will have a single entry mapped from the supplied * default value.

* *

If this annotation is not used and the corresponding metadata is not * present in the request, the value will be an empty collection for * List, Set or SortedSet, null for * other object types, and the Java-defined default for primitive types.

* * @see PathParam * @see QueryParam * @see FormParam * @see HeaderParam * @see MatrixParam * @see CookieParam */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface DefaultValue { /** * The default value. */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/Encoded.java000066400000000000000000000024301136334242300213040ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Encoded.java * * Created on June 29, 2007, 11:40 AM * */ package javax.ws.rs; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * 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. * * @see QueryParam * @see MatrixParam * @see PathParam * @see FormParam */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Encoded { } libjsr311-api-java-1.1.1/javax/ws/rs/FormParam.java000066400000000000000000000050411136334242300216300ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * FormParam.java * * Created on November 16, 2006, 2:04 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value(s) of a form parameter contained within a request entity body * 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 an unsupported media type, the * default value is used. * * The type T of the annotated parameter must either: *
    *
  1. Be a primitive type
  2. *
  3. Have a constructor that accepts a single String argument
  4. *
  5. Have a static method named valueOf or fromString * that accepts a single * String argument (see, for example, {@link Integer#valueOf(String)})
  6. *
  7. Be List<T>, Set<T> or * SortedSet<T>, where T satisfies 2 or 3 above. * The resulting collection is read-only.
  8. *
* *

If the type is not one of those listed in 4 above then the first value * (lexically) of the parameter is used.

* *

Note that, whilst the annotation target permits use on fields and methods, * this annotation is only required to be supported on resource method * parameters.

* * @see DefaultValue * @see Encoded */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @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. 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", * not "a+b" or "a%20b". */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/GET.java000066400000000000000000000015501136334242300203640ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * GET.java * * Created on October 24, 2007, 5:12 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP GET requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.GET) public @interface GET { } libjsr311-api-java-1.1.1/javax/ws/rs/HEAD.java000066400000000000000000000015541136334242300204520ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * HEAD.java * * Created on October 24, 2007, 5:12 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP HEAD requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.HEAD) public @interface HEAD { } libjsr311-api-java-1.1.1/javax/ws/rs/HeaderParam.java000066400000000000000000000045671136334242300221310ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * HeaderParam.java * * Created on January 24, 2007, 2:33 PM * */ package javax.ws.rs; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value(s) of a HTTP header to a resource method parameter, * resource class field, or resource class bean property. A default value * can be specified using the {@link DefaultValue} annotation. * * The type T of the annotated parameter, field or property * must either: *
    *
  1. Be a primitive type
  2. *
  3. Have a constructor that accepts a single String argument
  4. *
  5. Have a static method named valueOf or fromString * that accepts a single * String argument (see, for example, {@link Integer#valueOf(String)})
  6. *
  7. Be List<T>, Set<T> or * SortedSet<T>, where T satisfies 2 or 3 above. * The resulting collection is read-only.
  8. *
* *

If the type is not one of those listed in 4 above then the first value * (lexically) of the header is used.

* *

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.

* * @see DefaultValue * @see javax.ws.rs.core.HttpHeaders */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface HeaderParam { /** * Defines the name of the HTTP header whose value will be used * to initialize the value of the annotated method argument, class field or * bean property. Case insensitive. */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/HttpMethod.java000066400000000000000000000035221136334242300220260ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * HttpMethod.java * * Created on October 25, 2006, 2:02 PM * */ package javax.ws.rs; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Associates the name of a HTTP method with an annotation. A Java method annotated * with a runtime annotation that is itself annotated with this annotation will * be used to handle HTTP requests of the indicated HTTP method. It is an error * for a method to be annotated with more than one annotation that is annotated * with {@code HttpMethod}. * * @see GET * @see POST * @see PUT * @see DELETE * @see HEAD */ @Target({ElementType.ANNOTATION_TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface HttpMethod { /** * HTTP GET method */ public static final String GET="GET"; /** * HTTP POST method */ public static final String POST="POST"; /** * HTTP PUT method */ public static final String PUT="PUT"; /** * HTTP DELETE method */ public static final String DELETE="DELETE"; /** * HTTP HEAD method */ public static final String HEAD="HEAD"; /** * HTTP OPTIONS method */ public static final String OPTIONS="OPTIONS"; /** * Specifies the name of a HTTP method. E.g. "GET". */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/MatrixParam.java000066400000000000000000000053641136334242300222010ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * MatrixParam.java * * Created on January 24, 2007, 2:40 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value(s) of a URI matrix parameter 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. * * The type T of the annotated parameter, field or property must * either: *
    *
  1. Be a primitive type
  2. *
  3. Have a constructor that accepts a single String argument
  4. *
  5. Have a static method named valueOf or fromString * that accepts a single * String argument (see, for example, {@link Integer#valueOf(String)})
  6. *
  7. Be List<T>, Set<T> or * SortedSet<T>, where T satisfies 2 or 3 above. * The resulting collection is read-only.
  8. *
* *

If the type is not one of those listed in 4 above then the first value * (lexically) of the parameter is used.

* *

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.

* * @see DefaultValue * @see Encoded * @see Matrix URIs */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface MatrixParam { /** * 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. 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", not "a+b" or "a%20b". */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/OPTIONS.java000066400000000000000000000015551136334242300211050ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * OPTIONS.java * * Created on March 10, 2009 * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP OPTIONS requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.OPTIONS) public @interface OPTIONS { } libjsr311-api-java-1.1.1/javax/ws/rs/POST.java000066400000000000000000000015541136334242300205360ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * POST.java * * Created on October 24, 2007, 5:12 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP POST requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.POST) public @interface POST { } libjsr311-api-java-1.1.1/javax/ws/rs/PUT.java000066400000000000000000000015501136334242300204150ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * PUT.java * * Created on October 24, 2007, 5:12 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Indicates that the annotated method responds to HTTP PUT requests * @see HttpMethod */ @Target({ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) @HttpMethod(HttpMethod.PUT) public @interface PUT { } libjsr311-api-java-1.1.1/javax/ws/rs/Path.java000066400000000000000000000107301136334242300206410ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Path.java * * Created on September 15, 2006, 2:33 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Identifies the URI path that a resource class or class method will serve * requests for. * *

Paths are relative. For an annotated class the base URI is the * application path, see {@link javax.ws.rs.ApplicationPath}. For an annotated * method the base URI is the * effective URI of the containing class. For the purposes of absolutizing a * path against the base URI , a leading '/' in a path is * ignored and base URIs are treated as if they ended in '/'. E.g.:

* *
@Path("widgets")
 *public class WidgetsResource {
 *  @GET
 *  String getList() {...}
 * 
 *  @GET @Path("{id}")
 *  String getWidget(@PathParam("id") String id) {...}
 *}
* *

In the above, if the application path is * catalogue and the application is deployed at * http://example.com/, then GET requests for * http://example.com/catalogue/widgets will be handled by the * getList method while requests for * http://example.com/catalogue/widgets/nnn (where * nnn is some value) will be handled by the * getWidget method. The same would apply if the value of either * @Path annotation started with '/'. * *

Classes and methods may also be annotated with {@link Consumes} and * {@link Produces} to filter the requests they will receive.

* * @see Consumes * @see Produces * @see PathParam */ @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface Path { /** * Defines a URI template for the resource class or method, must not * include matrix parameters. * *

Embedded template parameters are allowed and are of the form:

* *
 param = "{" *WSP name *WSP [ ":" *WSP regex *WSP ] "}"
     * name = (ALPHA / DIGIT / "_")*(ALPHA / DIGIT / "." / "_" / "-" ) ; \w[\w\.-]*
     * regex = *( nonbrace / "{" *nonbrace "}" ) ; where nonbrace is any char other than "{" and "}"
* *

See {@link RFC 5234} * for a description of the syntax used above and the expansions of * {@code WSP}, {@code ALPHA} and {@code DIGIT}. In the above {@code name} * is the template parameter name and the optional {@code regex} specifies * the contents of the capturing group for the parameter. If {@code regex} * is not supplied then a default value of {@code [^/]+} which terminates at * a path segment boundary, is used. Matching of request URIs to URI * templates is performed against encoded path values and implementations * will not escape literal characters in regex automatically, therefore any * literals in {@code regex} should be escaped by the author according to * the rules of * {@link RFC 3986 section 3.3}. * Caution is recommended in the use of {@code regex}, incorrect use can * lead to a template parameter matching unexpected URI paths. See * {@link Pattern} * for further information on the syntax of regular expressions. * Values of template parameters may be extracted using {@link PathParam}. * *

The literal part of the supplied value (those characters * that are not part of a template parameter) is automatically percent * encoded to conform to the {@code path} production of * {@link RFC 3986 section 3.3}. * Note that percent encoded values are allowed in the literal part of the * value, an implementation will recognize such values and will not double * encode the '%' character.

*/ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/PathParam.java000066400000000000000000000065241136334242300216300ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * PathParam.java * * Created on November 16, 2006, 2:04 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value of a URI template parameter or a path segment * containing the template parameter to a resource method parameter, resource * class field, or resource class * bean property. The value is URL decoded unless this * is disabled using the {@link Encoded} annotation. * A default value can be specified using the {@link DefaultValue} * annotation. * * The type of the annotated parameter, field or property must either: * * *

The injected value corresponds to the latest use (in terms of scope) of * the path parameter. E.g. if a class and a sub-resource method are both * annotated with a {@link Path} containing the same URI template parameter, use * of {@code PathParam} on a subresource method parameter will bind the value * matching URI template parameter in the method's {@link Path} annotation.

* *

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.

* * @see Encoded * @see DefaultValue * @see javax.ws.rs.core.PathSegment * @see javax.ws.rs.core.UriInfo */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface PathParam { /** * Defines the name of the URI template parameter whose value will be used * to initialize the value of the annotated method parameter, class field or * property. See {@link Path#value()} for a description of the syntax of * template parameters. * *

E.g. a class annotated with: @Path("widgets/{id}") * can have methods annotated whose arguments are annotated * with @PathParam("id"). */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/Produces.java000066400000000000000000000037351136334242300215400ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Produces.java * * Created on September 15, 2006, 2:40 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Defines the media type(s) that the methods of a resource class or * {@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 * one of the media types requested in the HTTP request. If no such method is * available the container must respond with a HTTP "406 Not Acceptable" as * specified by RFC 2616. * *

A method for which there is a single-valued Produces * is not required to set the media type of representations that it produces: * the container will use the value of the Produces when * sending a response.

* * @see javax.ws.rs.ext.MessageBodyWriter */ @Inherited @Target({ElementType.TYPE, ElementType.METHOD}) @Retention(RetentionPolicy.RUNTIME) public @interface Produces { /** * A list of media types. Each entry may specify a single type or consist * of a comma separated list of types. E.g. {"image/jpeg,image/gif", * "image/png"}. Use of the comma-separated form allows definition of a * common string constant for use on multiple targets. */ String[] value() default "*/*"; } libjsr311-api-java-1.1.1/javax/ws/rs/QueryParam.java000066400000000000000000000053271136334242300220410ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * QueryParam.java * * Created on November 16, 2006, 2:04 PM * */ package javax.ws.rs; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Binds the value(s) of a HTTP query parameter 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. * * The type T of the annotated parameter, field or property must * either: *
    *
  1. Be a primitive type
  2. *
  3. Have a constructor that accepts a single String argument
  4. *
  5. Have a static method named valueOf or fromString * that accepts a single * String argument (see, for example, {@link Integer#valueOf(String)})
  6. *
  7. Be List<T>, Set<T> or * SortedSet<T>, where T satisfies 2 or 3 above. * The resulting collection is read-only.
  8. *
* *

If the type is not one of those listed in 4 above then the first value * (lexically) of the parameter is used.

* *

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.

* * @see DefaultValue * @see Encoded * @see javax.ws.rs.core.UriInfo#getQueryParameters */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface QueryParam { /** * 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. 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", not "a+b" or "a%20b". */ String value(); } libjsr311-api-java-1.1.1/javax/ws/rs/WebApplicationException.java000066400000000000000000000075511136334242300245340ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ package javax.ws.rs; import javax.ws.rs.core.Response; /** * Runtime exception for applications. *

* This exception may be thrown by a resource method, provider or * {@link javax.ws.rs.core.StreamingOutput} implementation if a specific * HTTP error response needs to be produced. Only effective if thrown prior to * the response being committed. * * @author Paul.Sandoz@Sun.Com */ public class WebApplicationException extends RuntimeException { private static final long serialVersionUID = 11660101L; private Response response; /** * Construct a new instance with a blank message and default HTTP status code of 500 */ public WebApplicationException() { this(null, Response.Status.INTERNAL_SERVER_ERROR); } /** * Construct a new instance using the supplied response * @param response the response that will be returned to the client, a value * of null will be replaced with an internal server error response (status * code 500) */ public WebApplicationException(Response response) { this(null,response); } /** * Construct a new instance with a blank message and specified HTTP status code * @param status the HTTP status code that will be returned to the client */ public WebApplicationException(int status) { this(null, status); } /** * Construct a new instance with a blank message and specified HTTP status code * @param status the HTTP status code that will be returned to the client * @throws IllegalArgumentException if status is null */ public WebApplicationException(Response.Status status) { this(null, status); } /** * Construct a new instance with a blank message and default HTTP status code of 500 * @param cause the underlying cause of the exception */ public WebApplicationException(Throwable cause) { this(cause,Response.Status.INTERNAL_SERVER_ERROR); } /** * Construct a new instance using the supplied response * @param response the response that will be returned to the client, a value * of null will be replaced with an internal server error response (status * code 500) * @param cause the underlying cause of the exception */ public WebApplicationException(Throwable cause, Response response) { super(cause); if (response==null) this.response = Response.serverError().build(); else this.response = response; } /** * Construct a new instance with a blank message and specified HTTP status code * @param status the HTTP status code that will be returned to the client * @param cause the underlying cause of the exception */ public WebApplicationException(Throwable cause, int status) { this(cause, Response.status(status).build()); } /** * Construct a new instance with a blank message and specified HTTP status code * @param status the HTTP status code that will be returned to the client * @param cause the underlying cause of the exception * @throws IllegalArgumentException if status is null */ public WebApplicationException(Throwable cause, Response.Status status) { this(cause, Response.status(status).build()); } /** * Get the HTTP response. * * @return the HTTP response. */ public Response getResponse() { return response; } } libjsr311-api-java-1.1.1/javax/ws/rs/core/000077500000000000000000000000001136334242300200315ustar00rootroot00000000000000libjsr311-api-java-1.1.1/javax/ws/rs/core/Application.java000066400000000000000000000052441136334242300231440ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ package javax.ws.rs.core; import java.util.Collections; import java.util.Set; /** * Defines the components of a JAX-RS application and supplies additional * metadata. A JAX-RS application or implementation supplies a concrete * subclass of this abstract class. * *

The implementation-created instance of an Application subclass may be * injected into resource classes and providers using * {@link javax.ws.rs.core.Context}.

* */ public class Application { private static final Set emptyObjectSet = Collections.emptySet(); private static final Set> emptyClassSet = Collections.emptySet(); /** * Get a set of root resource and provider classes. The default lifecycle * for resource class instances is per-request. The default lifecycle for * providers is singleton. * *

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. Implementations MUST * NOT modify the returned set.

* *

The default implementation returns an empty set.

* * @return a set of root resource and provider classes. Returning null * is equivalent to returning an empty set. */ public Set> getClasses() { return emptyClassSet; } /** * Get a set of root resource and provider instances. Fields and properties * of returned instances are injected with their declared dependencies * (see {@link Context}) by the runtime prior to use. * *

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. Implementations MUST * NOT modify the returned set.

* *

The default implementation returns an empty set.

* * @return a set of root resource and provider instances. Returning null * is equivalent to returning an empty set. */ public Set getSingletons() { return emptyObjectSet; } } libjsr311-api-java-1.1.1/javax/ws/rs/core/CacheControl.java000066400000000000000000000331171136334242300232450ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * CacheControl.java * * Created on March 5, 2007, 3:36 PM */ package javax.ws.rs.core; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import javax.ws.rs.ext.RuntimeDelegate; import javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate; /** * An abstraction for the value of a HTTP Cache-Control response header. * @see HTTP/1.1 section 14.9 */ public class CacheControl { private boolean _private; private List privateFields; private boolean noCache; private List noCacheFields; private boolean noStore; private boolean noTransform; private boolean mustRevalidate; private boolean proxyRevalidate; private int maxAge = -1; private int sMaxAge = -1; private Map cacheExtension; private static final HeaderDelegate delegate = RuntimeDelegate.getInstance().createHeaderDelegate(CacheControl.class); /** * Create a new instance of CacheControl. The new instance will have the * following default settings: * *
    *
  • private = false
  • *
  • noCache = false
  • *
  • noStore = false
  • *
  • noTransform = true
  • *
  • mustRevalidate = false
  • *
  • proxyRevalidate = false
  • *
  • An empty list of private fields
  • *
  • An empty list of no-cache fields
  • *
  • An empty map of cache extensions
  • *
*/ public CacheControl() { _private = false; noCache = false; noStore = false; noTransform = true; mustRevalidate = false; proxyRevalidate = false; } /** * Creates a new instance of CacheControl by parsing the supplied string. * @param value the cache control string * @return the newly created CacheControl * @throws IllegalArgumentException if the supplied string cannot be parsed * or is null */ public static CacheControl valueOf(String value) throws IllegalArgumentException { return delegate.fromString(value); } /** * Corresponds to the must-revalidate cache control directive. * @return true if the must-revalidate cache control directive will be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.4 */ public boolean isMustRevalidate() { return mustRevalidate; } /** * Corresponds to the must-revalidate cache control directive. * @param mustRevalidate true if the must-revalidate cache control directive should be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.4 */ public void setMustRevalidate(boolean mustRevalidate) { this.mustRevalidate = mustRevalidate; } /** * Corresponds to the proxy-revalidate cache control directive. * @return true if the proxy-revalidate cache control directive will be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.4 */ public boolean isProxyRevalidate() { return proxyRevalidate; } /** * Corresponds to the must-revalidate cache control directive. * @param proxyRevalidate true if the proxy-revalidate cache control directive should be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.4 */ public void setProxyRevalidate(boolean proxyRevalidate) { this.proxyRevalidate = proxyRevalidate; } /** * Corresponds to the max-age cache control directive. * @return the value of the max-age cache control directive, -1 if the directive is disabled. * @see HTTP/1.1 section 14.9.3 */ public int getMaxAge() { return maxAge; } /** * Corresponds to the max-age cache control directive. * @param maxAge the value of the max-age cache control directive, a value of -1 will disable the directive. * @see HTTP/1.1 section 14.9.3 */ public void setMaxAge(int maxAge) { this.maxAge = maxAge; } /** * Corresponds to the s-maxage cache control directive. * @return the value of the s-maxage cache control directive, -1 if the directive is disabled. * @see HTTP/1.1 section 14.9.3 */ public int getSMaxAge() { return sMaxAge; } /** * Corresponds to the s-maxage cache control directive. * @param sMaxAge the value of the s-maxage cache control directive, a value of -1 will disable the directive. * @see HTTP/1.1 section 14.9.3 */ public void setSMaxAge(int sMaxAge) { this.sMaxAge = sMaxAge; } /** * Corresponds to the value of the no-cache cache control directive. * @return a mutable list of field-names that will form the value of the no-cache cache control directive. * An empty list results in a bare no-cache directive. * @see #isNoCache * @see #setNoCache * @see HTTP/1.1 section 14.9.1 */ public List getNoCacheFields() { if (noCacheFields == null) noCacheFields = new ArrayList(); return noCacheFields; } /** * Corresponds to the no-cache cache control directive. * @param noCache true if the no-cache cache control directive should be included in the * response, false otherwise. * @see #getNoCacheFields * @see HTTP/1.1 section 14.9.1 */ public void setNoCache(boolean noCache) { this.noCache = noCache; } /** * Corresponds to the no-cache cache control directive. * @return true if the no-cache cache control directive will be included in the * response, false otherwise. * @see #getNoCacheFields * @see HTTP/1.1 section 14.9.1 */ public boolean isNoCache() { return noCache; } /** * Corresponds to the private cache control directive. * @return true if the private cache control directive will be included in the * response, false otherwise. * @see #getPrivateFields * @see HTTP/1.1 section 14.9.1 */ public boolean isPrivate() { return _private; } /** * Corresponds to the value of the private cache control directive. * @return a mutable list of field-names that will form the value of the private cache control directive. * An empty list results in a bare no-cache directive. * @see #isPrivate * @see #setPrivate * @see HTTP/1.1 section 14.9.1 */ public List getPrivateFields() { if (privateFields == null) privateFields = new ArrayList(); return privateFields; } /** * Corresponds to the private cache control directive. * @param _private true if the private cache control directive should be included in the * response, false otherwise. * @see #getPrivateFields * @see HTTP/1.1 section 14.9.1 */ public void setPrivate(boolean _private) { this._private = _private; } /** * Corresponds to the no-transform cache control directive. * @return true if the no-transform cache control directive will be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.5 */ public boolean isNoTransform() { return noTransform; } /** * Corresponds to the no-transform cache control directive. * @param noTransform true if the no-transform cache control directive should be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.5 */ public void setNoTransform(boolean noTransform) { this.noTransform = noTransform; } /** * Corresponds to the no-store cache control directive. * @return true if the no-store cache control directive will be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.2 */ public boolean isNoStore() { return noStore; } /** * Corresponds to the no-store cache control directive. * @param noStore true if the no-store cache control directive should be included in the * response, false otherwise. * @see HTTP/1.1 section 14.9.2 */ public void setNoStore(boolean noStore) { this.noStore = noStore; } /** * Corresponds to a set of extension cache control directives. * @return a mutable map of cache control extension names and their values. * If a key has a null value, it will appear as a bare directive. If a key has * a value that contains no whitespace then the directive will appear as * a simple name=value pair. If a key has a value that contains whitespace * then the directive will appear as a quoted name="value" pair. * @see HTTP/1.1 section 14.9.6 */ public Map getCacheExtension() { if (cacheExtension == null) cacheExtension = new HashMap(); return cacheExtension; } /** * Convert the cache control to a string suitable for use as the value of the * corresponding HTTP header. * @return a stringified cache control */ @Override public String toString() { return delegate.toString(this); } /** * Generate hash code from cache control properties. * @return the hashCode */ @Override public int hashCode() { int hash = 7; hash = 41 * hash + (this._private ? 1 : 0); hash = 41 * hash + (this.privateFields != null ? this.privateFields.hashCode() : 0); hash = 41 * hash + (this.noCache ? 1 : 0); hash = 41 * hash + (this.noCacheFields != null ? this.noCacheFields.hashCode() : 0); hash = 41 * hash + (this.noStore ? 1 : 0); hash = 41 * hash + (this.noTransform ? 1 : 0); hash = 41 * hash + (this.mustRevalidate ? 1 : 0); hash = 41 * hash + (this.proxyRevalidate ? 1 : 0); hash = 41 * hash + this.maxAge; hash = 41 * hash + this.sMaxAge; hash = 41 * hash + (this.cacheExtension != null ? this.cacheExtension.hashCode() : 0); return hash; } /** * Compares obj to this cache control to see if they are the same * considering all property values. * @param obj the object to compare to * @return true if the two cache controls are the same, false otherwise. */ @Override public boolean equals(Object obj) { if (obj == null) { return false; } if (getClass() != obj.getClass()) { return false; } final CacheControl other = (CacheControl) obj; if (this._private != other._private) { return false; } if (this.privateFields != other.privateFields && (this.privateFields == null || !this.privateFields.equals(other.privateFields))) { return false; } if (this.noCache != other.noCache) { return false; } if (this.noCacheFields != other.noCacheFields && (this.noCacheFields == null || !this.noCacheFields.equals(other.noCacheFields))) { return false; } if (this.noStore != other.noStore) { return false; } if (this.noTransform != other.noTransform) { return false; } if (this.mustRevalidate != other.mustRevalidate) { return false; } if (this.proxyRevalidate != other.proxyRevalidate) { return false; } if (this.maxAge != other.maxAge) { return false; } if (this.sMaxAge != other.sMaxAge) { return false; } if (this.cacheExtension != other.cacheExtension && (this.cacheExtension == null || !this.cacheExtension.equals(other.cacheExtension))) { return false; } return true; } } libjsr311-api-java-1.1.1/javax/ws/rs/core/Context.java000066400000000000000000000021141136334242300223160ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Context.java * * Created on November 16, 2006, 3:37 PM * */ package javax.ws.rs.core; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * This annotation is used to inject information into a class * field, bean property or method parameter. * @see Application * @see UriInfo * @see Request * @see HttpHeaders * @see SecurityContext * @see javax.ws.rs.ext.Providers */ @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Context { } libjsr311-api-java-1.1.1/javax/ws/rs/core/Cookie.java000066400000000000000000000132141136334242300221060ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Cookie.java * * Created on March 12, 2007, 5:01 PM * */ package javax.ws.rs.core; import javax.ws.rs.ext.RuntimeDelegate; import javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate; /** * Represents the value of a HTTP cookie, transferred in a request. * RFC 2109 specifies the legal characters for name, * value, path and domain. The default version of 1 corresponds to RFC 2109. * @see IETF RFC 2109 */ public class Cookie { /** * Cookies using the default version correspond to RFC 2109. */ public static final int DEFAULT_VERSION = 1; private static final HeaderDelegate delegate = RuntimeDelegate.getInstance().createHeaderDelegate(Cookie.class); private String name; private String value; private int version; private String path; private String domain; /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @param path the URI path for which the cookie is valid * @param domain the host domain for which the cookie is valid * @param version the version of the specification to which the cookie complies * @throws IllegalArgumentException if name is null */ public Cookie(String name, String value, String path, String domain, int version) { if (name == null) throw new IllegalArgumentException("name==null"); this.name = name; this.value = value; this.version = version; this.domain = domain; this.path = path; } /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @param path the URI path for which the cookie is valid * @param domain the host domain for which the cookie is valid * @throws IllegalArgumentException if name is null */ public Cookie(String name, String value, String path, String domain) { this(name, value, path, domain, DEFAULT_VERSION); } /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @throws IllegalArgumentException if name is null */ public Cookie(String name, String value) { this(name, value, null, null); } /** * Creates a new instance of Cookie by parsing the supplied string. * @param value the cookie string * @return the newly created Cookie * @throws IllegalArgumentException if the supplied string cannot be parsed * or is null */ public static Cookie valueOf(String value) throws IllegalArgumentException { return delegate.fromString(value); } /** * Get the name of the cookie * @return the name */ public String getName() { return name; } /** * Get the value of the cookie * @return the value */ public String getValue() { return value; } /** * Get the version of the cookie * @return the version */ public int getVersion() { return version; } /** * Get the domain of the cookie * @return the domain */ public String getDomain() { return domain; } /** * Get the path of the cookie * @return the path */ public String getPath() { return path; } /** * Convert the cookie to a string suitable for use as the value of the * corresponding HTTP header. * @return a stringified cookie */ @Override public String toString() { return delegate.toString(this); } /** * Generate a hashcode by hashing all of the cookies properties * @return the hashcode */ @Override public int hashCode() { int hash = 7; hash = 97 * hash + (this.name != null ? this.name.hashCode() : 0); hash = 97 * hash + (this.value != null ? this.value.hashCode() : 0); hash = 97 * hash + this.version; hash = 97 * hash + (this.path != null ? this.path.hashCode() : 0); hash = 97 * hash + (this.domain != null ? this.domain.hashCode() : 0); return hash; } /** * Compare for equality * @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. */ @Override public boolean equals(Object obj) { if (obj == null) { return false; } if (getClass() != obj.getClass()) { return false; } final Cookie other = (Cookie) obj; if (this.name != other.name && (this.name == null || !this.name.equals(other.name))) { return false; } if (this.value != other.value && (this.value == null || !this.value.equals(other.value))) { return false; } if (this.version != other.version) { return false; } if (this.path != other.path && (this.path == null || !this.path.equals(other.path))) { return false; } if (this.domain != other.domain && (this.domain == null || !this.domain.equals(other.domain))) { return false; } return true; } } libjsr311-api-java-1.1.1/javax/ws/rs/core/EntityTag.java000066400000000000000000000071341136334242300226110ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * EntityTag.java * * Created on March 21, 2007, 3:14 PM * */ package javax.ws.rs.core; import javax.ws.rs.ext.RuntimeDelegate; import javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate; /** * An abstraction for the value of a HTTP Entity Tag, used as the value * of an ETag response header. * @see HTTP/1.1 section 3.11 */ public class EntityTag { private String value; private boolean weak; private static final HeaderDelegate delegate = RuntimeDelegate.getInstance().createHeaderDelegate(EntityTag.class); /** * Creates a new instance of a strong EntityTag. * @param value the value of the tag, quotes not included. * @throws IllegalArgumentException if value is null */ public EntityTag(String value) { this(value, false); } /** * Creates a new instance of an EntityTag * @param value the value of the tag, quotes not included. * @param weak true if this represents a weak tag, false otherwise * @throws IllegalArgumentException if value is null */ public EntityTag(String value, boolean weak) { if (value == null) throw new IllegalArgumentException("value==null"); this.value = value; this.weak = weak; } /** * Creates a new instance of EntityTag by parsing the supplied string. * @param value the entity tag string * @return the newly created EntityTag * @throws IllegalArgumentException if the supplied string cannot be parsed * or is null */ public static EntityTag valueOf(String value) throws IllegalArgumentException { return delegate.fromString(value); } /** * Check the strength of an EntityTag * @return true if this represents a weak tag, false otherwise */ public boolean isWeak() { return weak; } /** * Get the value of an EntityTag * @return the value of the tag */ public String getValue() { return value; } /** * Compares obj to this tag to see if they are the same considering weakness and * value. * @param obj the object to compare to * @return true if the two tags are the same, false otherwise. */ @Override public boolean equals(Object obj) { if (obj == null) return false; if (!(obj instanceof EntityTag)) return super.equals(obj); EntityTag other = (EntityTag)obj; if (value.equals(other.getValue()) && weak==other.isWeak()) return true; return false; } /** * Generate hashCode based on value and weakness. * @return the hashCode */ @Override public int hashCode() { int hash = 3; hash = 17 * hash + (this.value != null ? this.value.hashCode() : 0); hash = 17 * hash + (this.weak ? 1 : 0); return hash; } /** * Convert the entity tag to a string suitable for use as the value of the * corresponding HTTP header. * @return a stringified entity tag */ @Override public String toString() { return delegate.toString(this); } } libjsr311-api-java-1.1.1/javax/ws/rs/core/GenericEntity.java000066400000000000000000000157471136334242300234630ustar00rootroot00000000000000package javax.ws.rs.core; /* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. * * This file incorporates work covered by the following copyright and * permission notice: * * Copyright (C) 2006 Google Inc. * * Licensed 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. */ import java.lang.reflect.GenericArrayType; import java.lang.reflect.ParameterizedType; import java.lang.reflect.Type; import javax.ws.rs.ext.MessageBodyWriter; /** * Represents a response entity of a generic type {@code T}. * *

Normally type erasure removes generic type information such that a * {@link Response} instance that contains, e.g., an entity of type * {@code List} appears to contain a raw {@code List} at runtime. * When the generic type is required to select a suitable * {@link MessageBodyWriter}, this class may be used to wrap the entity and * capture its generic type.

* *

There are two ways to create an instance:

*
    *
  1. Create a (typically anonymous) subclass of this * class which enables retrieval of the type information at runtime despite * type erasure. For example, the following code shows how to create a * {@link Response} containing an entity of type {@code List} whose * generic type will be available at runtime for selection of a suitable * {@link MessageBodyWriter}: * *
    List<String> list = new ArrayList<String>();
     *GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};
     *Response response = Response.ok(entity).build();
    * *

    where list is the instance of List<String> * that will form the response body and entity is an instance of an anonymous * subclass of {@code GenericEntity}.

  2. *
  3. Create an instance directly by supplying the generic type information * with the entity. For example the following code shows how to create * a response containing the result of a method invoked via reflection: *
    Method method = ...;
     *GenericEntity<Object> entity = new GenericEntity<Object>(
     *    method.invoke(...), method.getGenericReturnType());
     *Response response = Response.ok(entity).build();
  4. *

    The above obtains the generic type from the return type of the method, * the raw type is the class of entity.

    *
*/ public class GenericEntity { final Class rawType; final Type type; final T entity; /** * Constructs a new generic entity. Derives represented class from type * parameter. Note that this constructor is protected, users should create * a (usually anonymous) subclass as shown above. * * @param entity the entity instance, must not be null * @throws IllegalArgumentException if entity is null */ protected GenericEntity(T entity) { if (entity == null) { throw new IllegalArgumentException("The entity must not be null"); } this.entity = entity; this.type = getSuperclassTypeParameter(getClass()); this.rawType = entity.getClass(); } /** * Create a new instance of GenericEntity, supplying the generic type * information. The entity must be assignable to a variable of the * supplied generic type, e.g. if {@code entity} is an instance of * {@code ArrayList} then {@code genericType} could * be the same or a superclass of {@code ArrayList} with the same generic * type like {@code List}. * @param entity the entity instance, must not be null * @param genericType the generic type, must not be null * @throws IllegalArgumentException if the entity is not assignable to * a variable of the supplied generic type or if entity or genericType * is null. */ public GenericEntity(T entity, Type genericType) { if (entity == null || genericType==null) { throw new IllegalArgumentException("Arguments must not be null"); } this.entity = entity; this.rawType = entity.getClass(); checkTypeCompatibility(this.rawType, genericType); this.type = genericType; } private void checkTypeCompatibility(Class c, Type t) { if (t instanceof Class) { Class ct = (Class)t; if (ct.isAssignableFrom(c)) return; } else if (t instanceof ParameterizedType) { ParameterizedType pt = (ParameterizedType)t; Type rt = pt.getRawType(); checkTypeCompatibility(c, rt); return; } else if (c.isArray() && (t instanceof GenericArrayType)) { GenericArrayType at = (GenericArrayType)t; Type rt = at.getGenericComponentType(); checkTypeCompatibility(c.getComponentType(), rt); return; } throw new IllegalArgumentException("The type is incompatible with the class of the entity"); } /** * Returns the type from super class's type parameter. */ private static Type getSuperclassTypeParameter(Class subclass) { Type superclass = subclass.getGenericSuperclass(); if (!(superclass instanceof ParameterizedType)) { throw new RuntimeException("Missing type parameter."); } ParameterizedType parameterized = (ParameterizedType) superclass; return parameterized.getActualTypeArguments()[0]; } /** * Gets the raw type of the enclosed entity. Note that this is the raw type of * the instance, not the raw type of the type parameter. I.e. in the example * in the introduction, the raw type is {@code ArrayList} not {@code List}. * @return the raw type */ public final Class getRawType() { return rawType; } /** * Gets underlying {@code Type} instance. Note that this is derived from the * type parameter, not the enclosed instance. I.e. in the example * in the introduction, the type is {@code List} not * {@code ArrayList}. * @return the type */ public final Type getType() { return type; } /** * Get the enclosed entity * @return the enclosed entity */ public final T getEntity() { return entity; } }libjsr311-api-java-1.1.1/javax/ws/rs/core/HttpHeaders.java000066400000000000000000000201661136334242300231140ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * HttpHeaders.java * * Created on April 13, 2007, 3:00 PM * */ package javax.ws.rs.core; import java.util.List; import java.util.Locale; import java.util.Map; /** * An injectable interface that provides access to HTTP header information. * All methods throw java.lang.IllegalStateException if called outside the scope of a request * (e.g. from a provider constructor). * @see Context */ public interface HttpHeaders { /** * Get the values of a HTTP request header. The returned List is read-only. * This is a shortcut for getRequestHeaders().get(name). * @param name the header name, case insensitive * @return a read-only list of header values. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public List getRequestHeader(String name); /** * Get the values of HTTP request headers. The returned Map is case-insensitive * wrt keys and is read-only. * @return a read-only map of header names and values. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public MultivaluedMap getRequestHeaders(); /** * Get a list of media types that are acceptable for the response. * @return a read-only list of requested response media types sorted according * to their q-value, with highest preference first. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public List getAcceptableMediaTypes(); /** * Get a list of languages that are acceptable for the response. * @return a read-only list of acceptable languages sorted according * to their q-value, with highest preference first. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public List getAcceptableLanguages(); /** * Get the media type of the request entity * @return the media type or null if there is no request entity. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public MediaType getMediaType(); /** * Get the language of the request entity * @return the language of the entity or null if not specified * @throws java.lang.IllegalStateException if called outside the scope of a request */ public Locale getLanguage(); /** * Get any cookies that accompanied the request. * @return a read-only map of cookie name (String) to Cookie. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public Map getCookies(); /** * See {@link HTTP/1.1 documentation}. */ public static final String ACCEPT = "Accept"; /** * See {@link HTTP/1.1 documentation}. */ public static final String ACCEPT_CHARSET = "Accept-Charset"; /** * See {@link HTTP/1.1 documentation}. */ public static final String ACCEPT_ENCODING = "Accept-Encoding"; /** * See {@link HTTP/1.1 documentation}. */ public static final String ACCEPT_LANGUAGE = "Accept-Language"; /** * See {@link HTTP/1.1 documentation}. */ public static final String AUTHORIZATION = "Authorization"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CACHE_CONTROL = "Cache-Control"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CONTENT_ENCODING = "Content-Encoding"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CONTENT_LANGUAGE = "Content-Language"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CONTENT_LENGTH = "Content-Length"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CONTENT_LOCATION = "Content-Location"; /** * See {@link HTTP/1.1 documentation}. */ public static final String CONTENT_TYPE = "Content-Type"; /** * See {@link HTTP/1.1 documentation}. */ public static final String DATE = "Date"; /** * See {@link HTTP/1.1 documentation}. */ public static final String ETAG = "ETag"; /** * See {@link HTTP/1.1 documentation}. */ public static final String EXPIRES = "Expires"; /** * See {@link HTTP/1.1 documentation}. */ public static final String HOST = "Host"; /** * See {@link HTTP/1.1 documentation}. */ public static final String IF_MATCH = "If-Match"; /** * See {@link HTTP/1.1 documentation}. */ public static final String IF_MODIFIED_SINCE = "If-Modified-Since"; /** * See {@link HTTP/1.1 documentation}. */ public static final String IF_NONE_MATCH = "If-None-Match"; /** * See {@link HTTP/1.1 documentation}. */ public static final String IF_UNMODIFIED_SINCE = "If-Unmodified-Since"; /** * See {@link HTTP/1.1 documentation}. */ public static final String LAST_MODIFIED = "Last-Modified"; /** * See {@link HTTP/1.1 documentation}. */ public static final String LOCATION = "Location"; /** * See {@link HTTP/1.1 documentation}. */ public static final String USER_AGENT = "User-Agent"; /** * See {@link HTTP/1.1 documentation}. */ public static final String VARY = "Vary"; /** * See {@link HTTP/1.1 documentation}. */ public static final String WWW_AUTHENTICATE = "WWW-Authenticate"; /** * See {@link IETF RFC 2109}. */ public static final String COOKIE = "Cookie"; /** * See {@link IETF RFC 2109}. */ public static final String SET_COOKIE = "Set-Cookie"; } libjsr311-api-java-1.1.1/javax/ws/rs/core/MediaType.java000066400000000000000000000230451136334242300225610ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * MediaType.java * * Created on March 22, 2007, 2:35 PM * */ package javax.ws.rs.core; import java.util.Collections; import java.util.Comparator; import java.util.Map; import java.util.TreeMap; import javax.ws.rs.ext.RuntimeDelegate; import javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate; /** * An abstraction for a media type. Instances are immutable. * @see HTTP/1.1 section 3.7 */ public class MediaType { private String type; private String subtype; private Map parameters; /** * Empty immutable map used for all instances without parameters */ private static final Map emptyMap = Collections.emptyMap(); private static final HeaderDelegate delegate = RuntimeDelegate.getInstance().createHeaderDelegate(MediaType.class); /** The value of a type or subtype wildcard: "*" */ public static final String MEDIA_TYPE_WILDCARD = "*"; // Common media type constants /** "*/*" */ public final static String WILDCARD = "*/*"; /** "*/*" */ public final static MediaType WILDCARD_TYPE = new MediaType(); /** "application/xml" */ public final static String APPLICATION_XML = "application/xml"; /** "application/xml" */ public final static MediaType APPLICATION_XML_TYPE = new MediaType("application","xml"); /** "application/atom+xml" */ public final static String APPLICATION_ATOM_XML = "application/atom+xml"; /** "application/atom+xml" */ public final static MediaType APPLICATION_ATOM_XML_TYPE = new MediaType("application","atom+xml"); /** "application/xhtml+xml" */ public final static String APPLICATION_XHTML_XML = "application/xhtml+xml"; /** "application/xhtml+xml" */ public final static MediaType APPLICATION_XHTML_XML_TYPE = new MediaType("application","xhtml+xml"); /** "application/svg+xml" */ public final static String APPLICATION_SVG_XML = "application/svg+xml"; /** "application/svg+xml" */ public final static MediaType APPLICATION_SVG_XML_TYPE = new MediaType("application","svg+xml"); /** "application/json" */ public final static String APPLICATION_JSON = "application/json"; /** "application/json" */ public final static MediaType APPLICATION_JSON_TYPE = new MediaType("application","json"); /** "application/x-www-form-urlencoded" */ public final static String APPLICATION_FORM_URLENCODED = "application/x-www-form-urlencoded"; /** "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" */ public final static MediaType APPLICATION_OCTET_STREAM_TYPE = new MediaType("application","octet-stream"); /** "text/plain" */ public final static String TEXT_PLAIN = "text/plain"; /** "text/plain" */ public final static MediaType TEXT_PLAIN_TYPE = new MediaType("text","plain"); /** "text/xml" */ public final static String TEXT_XML = "text/xml"; /** "text/xml" */ public final static MediaType TEXT_XML_TYPE = new MediaType("text","xml"); /** "text/html" */ public final static String TEXT_HTML = "text/html"; /** "text/html" */ public final static MediaType TEXT_HTML_TYPE = new MediaType("text","html"); /** * Creates a new instance of MediaType by parsing the supplied string. * @param type the media type string * @return the newly created MediaType * @throws IllegalArgumentException if the supplied string cannot be parsed * or is null */ public static MediaType valueOf(String type) throws IllegalArgumentException { return delegate.fromString(type); } /** * Creates a new instance of MediaType with the supplied type, subtype and * 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 parameters) { this.type = type==null ? MEDIA_TYPE_WILDCARD : type; this.subtype = subtype==null ? MEDIA_TYPE_WILDCARD : subtype; if (parameters==null) { this.parameters = emptyMap; } else { Map map = new TreeMap(new Comparator() { public int compare(String o1, String o2) { return o1.compareToIgnoreCase(o2); } }); for (Map.Entry e: parameters.entrySet()) { map.put(e.getKey().toLowerCase(), e.getValue()); } this.parameters = Collections.unmodifiableMap(map); } } /** * Creates a new instance of MediaType with the supplied type and 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); } /** * Creates a new instance of MediaType, both type and subtype are wildcards. * Consider using the constant {@link #WILDCARD_TYPE} instead. */ public MediaType() { this(MEDIA_TYPE_WILDCARD, MEDIA_TYPE_WILDCARD); } /** * Getter for primary type. * @return value of primary type. */ public String getType() { return this.type; } /** * Checks if the primary type is a wildcard. * @return true if the primary type is a wildcard */ public boolean isWildcardType() { return this.getType().equals(MEDIA_TYPE_WILDCARD); } /** * Getter for subtype. * @return value of subtype. */ public String getSubtype() { return this.subtype; } /** * Checks if the subtype is a wildcard * @return true if the subtype is a wildcard */ public boolean isWildcardSubtype() { return this.getSubtype().equals(MEDIA_TYPE_WILDCARD); } /** * Getter for a read-only parameter map. Keys are case-insensitive. * @return an immutable map of parameters. */ public Map getParameters() { return parameters; } /** * Check if this media type is compatible with another media type. E.g. * image/* is compatible with image/jpeg, image/png, etc. Media type * parameters are ignored. The function is commutative. * @return true if the types are compatible, false otherwise. * @param other the media type to compare with */ public boolean isCompatible(MediaType other) { if (other == null) return false; if (type.equals(MEDIA_TYPE_WILDCARD) || other.type.equals(MEDIA_TYPE_WILDCARD)) return true; else if (type.equalsIgnoreCase(other.type) && (subtype.equals(MEDIA_TYPE_WILDCARD) || other.subtype.equals(MEDIA_TYPE_WILDCARD))) return true; else return this.type.equalsIgnoreCase(other.type) && this.subtype.equalsIgnoreCase(other.subtype); } /** * Compares obj to this media type to see if they are the same by comparing * type, subtype and parameters. Note that the case-sensitivity of parameter * values is dependent on the semantics of the parameter name, see * {@link HTTP/1.1}. * This method assumes that values are case-sensitive. * @param obj the object to compare to * @return true if the two media types are the same, false otherwise. */ @Override public boolean equals(Object obj) { if (obj == null) return false; if (!(obj instanceof MediaType)) return false; MediaType other = (MediaType)obj; return (this.type.equalsIgnoreCase(other.type) && this.subtype.equalsIgnoreCase(other.subtype) && this.parameters.equals(other.parameters)); } /** * Generate a hashcode from the type, subtype and parameters. * @return a hashcode */ @Override public int hashCode() { return (this.type.toLowerCase()+this.subtype.toLowerCase()).hashCode()+this.parameters.hashCode(); } /** * Convert the media type to a string suitable for use as the value of a * corresponding HTTP header. * @return a stringified media type */ @Override public String toString() { return delegate.toString(this); } } libjsr311-api-java-1.1.1/javax/ws/rs/core/MultivaluedMap.java000066400000000000000000000025661136334242300236360ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * MultivaluedMap.java * * Created on February 13, 2007, 2:30 PM * */ package javax.ws.rs.core; import java.util.List; import java.util.Map; /** * A map of key-values pairs. Each key can have zero or more values. * */ public interface MultivaluedMap extends Map> { /** * Set the key's value to be a one item list consisting of the supplied value. * Any existing values will be replaced. * * @param key the key * @param value the single value of the key */ void putSingle(K key, V value); /** * Add a value to the current list of values for the supplied key. * @param key the key * @param value the value to be added. */ void add(K key, V value); /** * A shortcut to get the first value of the supplied key. * @param key the key * @return the first value for the specified key or null if the key is * not in the map. */ V getFirst(K key); } libjsr311-api-java-1.1.1/javax/ws/rs/core/NewCookie.java000066400000000000000000000203761136334242300225670ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * NewCookie.java * * Created on March 12, 2007, 5:08 PM * */ package javax.ws.rs.core; import javax.ws.rs.ext.RuntimeDelegate; import javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate; /** * Used to create a new HTTP cookie, transferred in a response. * @see IETF RFC 2109 */ public class NewCookie extends Cookie { /** * Specifies that the cookie expires with the current application/browser session. */ public static final int DEFAULT_MAX_AGE = -1; private static final HeaderDelegate delegate = RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class); private String comment = null; private int maxAge = DEFAULT_MAX_AGE; private boolean secure = false; /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @throws IllegalArgumentException if name is null */ public NewCookie(String name, String value) { super(name, value); } /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @param path the URI path for which the cookie is valid * @param domain the host domain for which the cookie is valid * @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 name is null */ public NewCookie(String name, String value, String path, String domain, String comment, int maxAge, boolean secure) { super(name, value, path, domain); this.comment = comment; this.maxAge = maxAge; this.secure = secure; } /** * Create a new instance. * @param name the name of the cookie * @param value the value of the cookie * @param path the URI path for which the cookie is valid * @param domain the host domain for which the cookie is valid * @param version the version of the specification to which the cookie complies * @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 name is null */ public NewCookie(String name, String value, String path, String domain, int version, String comment, int maxAge, boolean secure) { super(name, value, path, domain, version); this.comment = comment; this.maxAge = maxAge; this.secure = secure; } /** * 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==null ? null : cookie.getName(), cookie==null ? null : cookie.getValue(), cookie==null ? null : cookie.getPath(), cookie==null ? null : cookie.getDomain(), cookie==null ? Cookie.DEFAULT_VERSION : cookie.getVersion()); } /** * Create a new instance supplementing the information in the supplied cookie. * @param cookie the cookie to clone * @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); this.comment = comment; this.maxAge = maxAge; this.secure = secure; } /** * Creates a new instance of NewCookie by parsing the supplied string. * @param value the cookie string * @return the newly created NewCookie * @throws IllegalArgumentException if the supplied string cannot be parsed * or is null */ public static NewCookie valueOf(String value) throws IllegalArgumentException { return delegate.fromString(value); } /** * Get the comment associated with the cookie. * @return the comment or null if none set */ public String getComment() { return comment; } /** * Get the maximum age of the the cookie in seconds. Cookies older than * the maximum age are discarded. A cookie can be unset by sending a new * cookie with maximum age of 0 since it will overwrite any existing cookie * and then be immediately discarded. The default value of -1 indicates that the cookie * will be discarded at the end of the browser/application session. * @return the maximum age in seconds */ public int getMaxAge() { return maxAge; } /** * Whether the cookie will only be sent over a secure connection. Defaults * to false. * @return true if the cookie will only be sent over a secure connection, * false otherwise. */ public boolean isSecure() { return secure; } /** * Obtain a new instance of a {@link Cookie} with the same name, value, path, * domain and version as this {@code NewCookie}. This method can be used to * obtain an object that can be compared for equality with another {@code Cookie}; * since a {@code Cookie} will never compare equal to a {@code NewCookie}. * @return a {@link Cookie} */ public Cookie toCookie() { return new Cookie(this.getName(),this.getValue(), this.getPath(), this.getDomain(), this.getVersion()); } /** * Convert the cookie to a string suitable for use as the value of the * corresponding HTTP header. * @return a stringified cookie */ @Override public String toString() { return delegate.toString(this); } /** * Generate a hashcode by hashing all of the properties * @return the hashcode */ @Override public int hashCode() { int hash = super.hashCode(); hash = 59 * hash + (this.comment != null ? this.comment.hashCode() : 0); hash = 59 * hash + this.maxAge; hash = 59 * hash + (this.secure ? 1 : 0); return hash; } /** * Compare for equality. Use {@link #toCookie()} to compare a * {@code NewCookie} to a {@code Cookie} considering only the common * properties. * @param obj * @return true if the object is a {@code NewCookie} with the same value for * all properties, false otherwise. */ @Override public boolean equals(Object obj) { if (obj == null) { return false; } if (getClass() != obj.getClass()) { return false; } final NewCookie other = (NewCookie) obj; if (this.getName() != other.getName() && (this.getName() == null || !this.getName().equals(other.getName()))) { return false; } if (this.getValue() != other.getValue() && (this.getValue() == null || !this.getValue().equals(other.getValue()))) { return false; } if (this.getVersion() != other.getVersion()) { return false; } if (this.getPath() != other.getPath() && (this.getPath() == null || !this.getPath().equals(other.getPath()))) { return false; } if (this.getDomain() != other.getDomain() && (this.getDomain() == null || !this.getDomain().equals(other.getDomain()))) { return false; } if (this.comment != other.comment && (this.comment == null || !this.comment.equals(other.comment))) { return false; } if (this.maxAge != other.maxAge) { return false; } if (this.secure != other.secure) { return false; } return true; } } libjsr311-api-java-1.1.1/javax/ws/rs/core/PathSegment.java000066400000000000000000000027621136334242300231220ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * PathSegment.java * * Created on January 30, 2007, 4:35 PM * */ package javax.ws.rs.core; /** * Represents a URI path segment and any associated matrix parameters. When an * 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 parameter values in * URI encoded form. * * @see UriInfo#getPathSegments * @see javax.ws.rs.PathParam */ public interface PathSegment { /** * Get the path segment. *

* @return the path segment */ String getPath(); /** * 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 Matrix URIs */ MultivaluedMap getMatrixParameters(); } libjsr311-api-java-1.1.1/javax/ws/rs/core/Request.java000066400000000000000000000132351136334242300223300ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Request.java * * Created on September 27, 2007, 5:39 PM * */ package javax.ws.rs.core; import java.util.Date; import java.util.List; import javax.ws.rs.core.Response.ResponseBuilder; /** * An injectable helper for request processing, all methods throw * java.lang.IllegalStateException if called outside the scope of a request * (e.g. from a provider constructor). * * Precondition processing (see the evaluatePreconditions methods) * can result in either a null return value to indicate that * preconditions have been met and that the request should continue, or * a non-null return value to indicate that preconditions were not met. In the * event that preconditions were not met, the returned ResponseBuilder * instance will have an appropriate status and will also include a Vary * header if the {@link #selectVariant} method was called prior to to calling * evaluatePreconditions. It is the responsibility of the caller * to check the status and add additional metadata if required. E.g., see * HTTP/1.1, section 10.3.5 * for details of the headers that are expected to accompany a 304 Not Modified * response. */ public interface Request { /** * Get the request method, e.g. GET, POST, etc. * @return the request method * @see javax.ws.rs.HttpMethod */ String getMethod(); /** * Select the representation variant that best matches the request. More * explicit variants are chosen ahead of less explicit ones. A vary header * is computed from the supplied list and automatically added to the * response. * * @param variants a list of Variant that describe all of the * available representation variants. * @return the variant that best matches the request. * @see Variant.VariantListBuilder * @throws java.lang.IllegalArgumentException if variants is empty or null * @throws java.lang.IllegalStateException if called outside the scope of a request */ Variant selectVariant(List variants) throws IllegalArgumentException; /** * Evaluate request preconditions based on the passed in value. * * @param eTag an ETag for the current state of the resource * @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); /** * Evaluate request preconditions based on the passed in value. * * @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); /** * Evaluate request preconditions based on the passed in value. * * @param lastModified a date that specifies the modification date of the resource * @param eTag an ETag for the current state of the resource * @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); /** * Evaluate request preconditions for a resource that does not currently * exist. The primary use of this method is to support the {@link * If-Match: *} and {@link * If-None-Match: *} preconditions. * *

Note that both preconditions If-None-Match: * and * If-None-Match: something will always be considered to * have been met and it is the applications responsibility * to enforce any additional method-specific semantics. E.g. a * PUT on a resource that does not exist might succeed whereas * a GET on a resource that does not exist would likely result * in a 404 response. It would be the responsibility of the application to * generate the 404 response.

* * @return null if the preconditions are met or a ResponseBuilder set with * the appropriate status if the preconditions are not met. * @throws java.lang.IllegalStateException if called outside the scope of * a request */ ResponseBuilder evaluatePreconditions(); } libjsr311-api-java-1.1.1/javax/ws/rs/core/Response.java000066400000000000000000000667161136334242300225120ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Response.java * * Created on April 18, 2007, 9:00 AM * */ package javax.ws.rs.core; import java.net.URI; import java.util.Date; import java.util.List; import java.util.Locale; import javax.ws.rs.ext.RuntimeDelegate; /** * Defines the contract between a returned instance and the runtime when * an application needs to provide metadata to the runtime. An application * class can extend this class directly or can use one of the static * methods to create an instance using a ResponseBuilder. * * Several methods have parameters of type URI, {@link UriBuilder} provides * convenient methods to create such values as does * {@link URI.create()}. * * @see Response.ResponseBuilder */ public abstract class Response { /** * Protected constructor, use one of the static methods to obtain a * {@link ResponseBuilder} instance and obtain a Response from that. */ protected Response() {} /** * Return the response entity. The response will be serialized using a * MessageBodyWriter for either the class of the entity or, in the case of * {@link GenericEntity}, the value of {@link GenericEntity#getRawType()}. * @return an object instance or null if there is no entity * @see javax.ws.rs.ext.MessageBodyWriter */ public abstract Object getEntity(); /** * Get the status code associated with the response. * @return the response status code or -1 if the status was not set. */ public abstract int getStatus(); /** * Get metadata associated with the response as a map. The returned map * may be subsequently modified by the JAX-RS runtime. Values will be * serialized using a {@link javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate} * if one is available via * {@link javax.ws.rs.ext.RuntimeDelegate#createHeaderDelegate(java.lang.Class)} * for the class of the value or using the values {@code toString} method if a * header delegate is not available. * @return response metadata as a map */ public abstract MultivaluedMap getMetadata(); /** * Create a new ResponseBuilder by performing a shallow copy of an * existing Response. The returned builder has its own metadata map but * entries are simply references to the keys and values contained in the * supplied Response metadata map. * @param response a Response from which the status code, entity and metadata * will be copied * @return a new ReponseBuilder */ public static ResponseBuilder fromResponse(Response response) { ResponseBuilder b = status(response.getStatus()); b.entity(response.getEntity()); for (String headerName: response.getMetadata().keySet()) { List headerValues = response.getMetadata().get(headerName); for (Object headerValue: headerValues) { b.header(headerName, headerValue); } } return b; } /** * Create a new ResponseBuilder with the supplied status. * @param status the response status * @return a new ResponseBuilder * @throws IllegalArgumentException if status is null */ public static ResponseBuilder status(StatusType status) { ResponseBuilder b = ResponseBuilder.newInstance(); b.status(status); return b; } /** * Create a new ResponseBuilder with the supplied status. * @param status the response status * @return a new ResponseBuilder * @throws IllegalArgumentException if status is null */ public static ResponseBuilder status(Status status) { return status((StatusType)status); } /** * 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(); b.status(status); return b; } /** * Create a new ResponseBuilder with an OK status. * * @return a new ResponseBuilder */ public static ResponseBuilder ok() { ResponseBuilder b = status(Status.OK); return b; } /** * 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 */ public static ResponseBuilder ok(Object entity) { ResponseBuilder b = ok(); b.entity(entity); return b; } /** * 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 * @return a new ResponseBuilder */ public static ResponseBuilder ok(Object entity, MediaType type) { ResponseBuilder b = ok(); b.entity(entity); b.type(type); return b; } /** * 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 * @return a new ResponseBuilder */ public static ResponseBuilder ok(Object entity, String type) { ResponseBuilder b = ok(); b.entity(entity); b.type(type); return b; } /** * 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 * @return a new ResponseBuilder */ public static ResponseBuilder ok(Object entity, Variant variant) { ResponseBuilder b = ok(); b.entity(entity); b.variant(variant); return b; } /** * Create a new ResponseBuilder with an server error status. * * @return a new ResponseBuilder */ public static ResponseBuilder serverError() { ResponseBuilder b = status(Status.INTERNAL_SERVER_ERROR); return b; } /** * Create a new ResponseBuilder for a created resource, set the location * header using the supplied value. * * @param location the URI of the new resource. If a relative URI is * 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); return b; } /** * Create a new ResponseBuilder for an empty response. * * @return a new ResponseBuilder */ public static ResponseBuilder noContent() { ResponseBuilder b = status(Status.NO_CONTENT); return b; } /** * Create a new ResponseBuilder with a not-modified status. * * @return a new ResponseBuilder */ public static ResponseBuilder notModified() { ResponseBuilder b = status(Status.NOT_MODIFIED); return b; } /** * Create a new ResponseBuilder with a not-modified status. * * @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(); b.tag(tag); return b; } /** * Create a new ResponseBuilder with a not-modified status * and a strong entity tag. This is a shortcut * for notModified(new EntityTag(value)). * * @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(); b.tag(tag); return b; } /** * Create a new ResponseBuilder for a redirection. Used in the * redirect-after-POST (aka POST/redirect/GET) pattern. * * @param location the redirection URI. If a relative URI is * supplied it will be converted into an absolute URI by resolving it * 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); return b; } /** * Create a new ResponseBuilder for a temporary redirection. * * @param location the redirection URI. If a relative URI is * supplied it will be converted into an absolute URI by resolving it * 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); return b; } /** * Create a new ResponseBuilder for a not acceptable response. * * @param variants list of variants that were available, a null value is * equivalent to an empty list. * @return a new ResponseBuilder */ public static ResponseBuilder notAcceptable(List variants) { ResponseBuilder b = status(Status.NOT_ACCEPTABLE).variants(variants); return b; } /** * A class used to build Response instances that contain metadata instead * of or in addition to an entity. An initial instance may be obtained via * static methods of the Response class, instance methods provide the * ability to set metadata. E.g. to create a response that indicates the * creation of a new resource: *
@POST
     * Response addWidget(...) {
     *   Widget w = ...
     *   URI widgetId = UriBuilder.fromResource(Widget.class)...
     *   return Response.created(widgetId).build();
     * }
* *

Several methods have parameters of type URI, {@link UriBuilder} provides * convenient methods to create such values as does URI.create().

* *

Where multiple variants of the same method are provided, the type of * the supplied parameter is retained in the metadata of the built * {@code Response}.

* */ public static abstract class ResponseBuilder { /** * Protected constructor, use one of the static methods of * Response to obtain an instance. */ protected ResponseBuilder() {} /** * Create a new builder instance. * * @return a new ResponseBuilder */ protected static ResponseBuilder newInstance() { ResponseBuilder b = RuntimeDelegate.getInstance().createResponseBuilder(); return b; } /** * Create a Response instance from the current ResponseBuilder. The builder * is reset to a blank state equivalent to calling the ok method. * * @return a Response instance */ public abstract Response build(); /** * Create a copy of the ResponseBuilder preserving its state. * @return a copy of the ResponseBuilder */ @Override public abstract ResponseBuilder clone(); /** * Set the status on the ResponseBuilder. * * @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); /** * Set the status on the ResponseBuilder. * * @param status the response status * @return the updated ResponseBuilder * @throws IllegalArgumentException if status is null */ public ResponseBuilder status(StatusType status) { if (status == null) throw new IllegalArgumentException(); return status(status.getStatusCode()); }; /** * Set the status on the ResponseBuilder. * * @param status the response status * @return the updated ResponseBuilder * @throws IllegalArgumentException if status is null */ public ResponseBuilder status(Status status) { return status((StatusType)status); }; /** * 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 */ public abstract ResponseBuilder entity(Object entity); /** * Set the response media type on the ResponseBuilder. * * @param type the media type of the response entity, if null any * existing value for type will be removed * @return the updated ResponseBuilder */ public abstract ResponseBuilder type(MediaType type); /** * Set the response media type on the ResponseBuilder. * * @param type the media type of the response entity, if null any * existing value for type will be removed * @return the updated ResponseBuilder * @throws IllegalArgumentException if type cannot be parsed */ public abstract ResponseBuilder type(String type); /** * Set representation metadata on the ResponseBuilder. Equivalent to * setting the values of content type, content language, and content * encoding separately using the values of the variant properties. * * @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); /** * Add a Vary header that lists the available variants. * * @param variants a list of available representation variants, a null * value will remove an existing value for vary. * @return the updated ResponseBuilder */ public abstract ResponseBuilder variants(List variants); /** * Set the language on the ResponseBuilder. * * @param language the language of the response entity, if null any * existing value for language will be removed * @return the updated ResponseBuilder */ public abstract ResponseBuilder language(String language); /** * Set the language on the ResponseBuilder. * * * @param language the language of the response entity, if null any * existing value for type will be removed * @return the updated ResponseBuilder */ public abstract ResponseBuilder language(Locale language); /** * Set the location on the ResponseBuilder. * * @param location the location. If a relative URI is * supplied it will be converted into an absolute URI by resolving it * relative to the base URI of the application (see * {@link UriInfo#getBaseUri}). If null any * existing value for location will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder location(URI location); /** * Set the content location on the ResponseBuilder. * * @param location the content location. Relative or absolute URIs * may be used for the value of content location. If null any * existing value for content location will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder contentLocation(URI location); /** * Set an entity tag on the ResponseBuilder. * * @param tag the entity tag, if null any * existing entity tag value will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder tag(EntityTag tag); /** * Set a strong entity tag on the ResponseBuilder. This is a shortcut * for tag(new EntityTag(value)). * * @param tag the string content of a strong entity tag. The JAX-RS * runtime will quote the supplied value when creating the header. If * null any existing entity tag value will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder tag(String tag); /** * Set the last modified date on the ResponseBuilder. * * @param lastModified the last modified date, if null any existing * last modified value will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder lastModified(Date lastModified); /** * Set the cache control data on the ResponseBuilder. * * @param cacheControl the cache control directives, if null removes any * existing cache control directives. * @return the updated ResponseBuilder */ public abstract ResponseBuilder cacheControl(CacheControl cacheControl); /** * Set the expires date on the ResponseBuilder. * * @param expires the expiration date, if null removes any existing * expires value. * @return the updated ResponseBuilder */ public abstract ResponseBuilder expires(Date expires); /** * Add a header to the ResponseBuilder. * * @param name the name of the header * @param value the value of the header, the header will be serialized * using a {@link javax.ws.rs.ext.RuntimeDelegate.HeaderDelegate} if * one is available via * {@link javax.ws.rs.ext.RuntimeDelegate#createHeaderDelegate(java.lang.Class)} * for the class of {@code value} or using its {@code toString} method if a * header delegate is not available. If {@code value} is null then all * current headers of the same name will be removed. * @return the updated ResponseBuilder */ public abstract ResponseBuilder header(String name, Object value); /** * Add cookies to the ResponseBuilder. * * @param cookies new cookies that will accompany the response. A null * value will remove all cookies, including those added via the * {@link #header(java.lang.String, java.lang.Object)} method. * @return the updated ResponseBuilder */ public abstract ResponseBuilder cookie(NewCookie... cookies); } /** * Base interface for statuses used in responses. */ public interface StatusType { /** * Get the associated status code * @return the status code */ public int getStatusCode(); /** * Get the class of status code * @return the class of status code */ public Status.Family getFamily(); /** * Get the reason phrase * @return the reason phrase */ public String getReasonPhrase(); } /** * Commonly used status codes defined by HTTP, see * {@link HTTP/1.1 documentation} * for the complete list. Additional status codes can be added by applications * by creating an implementation of {@link StatusType}. */ public enum Status implements StatusType { /** * 200 OK, see {@link HTTP/1.1 documentation}. */ OK(200, "OK"), /** * 201 Created, see {@link HTTP/1.1 documentation}. */ CREATED(201, "Created"), /** * 202 Accepted, see {@link HTTP/1.1 documentation}. */ ACCEPTED(202, "Accepted"), /** * 204 No Content, see {@link HTTP/1.1 documentation}. */ NO_CONTENT(204, "No Content"), /** * 301 Moved Permanently, see {@link HTTP/1.1 documentation}. */ MOVED_PERMANENTLY(301, "Moved Permanently"), /** * 303 See Other, see {@link HTTP/1.1 documentation}. */ SEE_OTHER(303, "See Other"), /** * 304 Not Modified, see {@link HTTP/1.1 documentation}. */ NOT_MODIFIED(304, "Not Modified"), /** * 307 Temporary Redirect, see {@link HTTP/1.1 documentation}. */ TEMPORARY_REDIRECT(307, "Temporary Redirect"), /** * 400 Bad Request, see {@link HTTP/1.1 documentation}. */ BAD_REQUEST(400, "Bad Request"), /** * 401 Unauthorized, see {@link HTTP/1.1 documentation}. */ UNAUTHORIZED(401, "Unauthorized"), /** * 403 Forbidden, see {@link HTTP/1.1 documentation}. */ FORBIDDEN(403, "Forbidden"), /** * 404 Not Found, see {@link HTTP/1.1 documentation}. */ NOT_FOUND(404, "Not Found"), /** * 406 Not Acceptable, see {@link HTTP/1.1 documentation}. */ NOT_ACCEPTABLE(406, "Not Acceptable"), /** * 409 Conflict, see {@link HTTP/1.1 documentation}. */ CONFLICT(409, "Conflict"), /** * 410 Gone, see {@link HTTP/1.1 documentation}. */ GONE(410, "Gone"), /** * 412 Precondition Failed, see {@link HTTP/1.1 documentation}. */ PRECONDITION_FAILED(412, "Precondition Failed"), /** * 415 Unsupported Media Type, see {@link HTTP/1.1 documentation}. */ UNSUPPORTED_MEDIA_TYPE(415, "Unsupported Media Type"), /** * 500 Internal Server Error, see {@link HTTP/1.1 documentation}. */ INTERNAL_SERVER_ERROR(500, "Internal Server Error"), /** * 503 Service Unavailable, see {@link HTTP/1.1 documentation}. */ SERVICE_UNAVAILABLE(503, "Service Unavailable"); private final int code; private final String reason; private Family family; /** * An enumeration representing the class of status code. Family is used * here since class is overloaded in Java. */ public enum Family {INFORMATIONAL, SUCCESSFUL, REDIRECTION, CLIENT_ERROR, SERVER_ERROR, OTHER}; Status(final int statusCode, final String reasonPhrase) { this.code = statusCode; this.reason = reasonPhrase; switch(code/100) { case 1: this.family = Family.INFORMATIONAL; break; case 2: this.family = Family.SUCCESSFUL; break; case 3: this.family = Family.REDIRECTION; break; case 4: this.family = Family.CLIENT_ERROR; break; case 5: this.family = Family.SERVER_ERROR; break; default: this.family = Family.OTHER; break; } } /** * Get the class of status code * @return the class of status code */ public Family getFamily() { return family; } /** * Get the associated status code * @return the status code */ public int getStatusCode() { return code; } /** * Get the reason phrase * @return the reason phrase */ public String getReasonPhrase() { return toString(); } /** * Get the reason phrase * @return the reason phrase */ @Override public String toString() { return reason; } /** * Convert a numerical status code into the corresponding Status * @param statusCode the numerical status code * @return the matching Status or null is no matching Status is defined */ public static Status fromStatusCode(final int statusCode) { for (Status s : Status.values()) { if (s.code == statusCode) { return s; } } return null; } } } libjsr311-api-java-1.1.1/javax/ws/rs/core/SecurityContext.java000066400000000000000000000064521136334242300240570ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ package javax.ws.rs.core; import java.security.Principal; /** * An injectable interface that provides access to security related * information. * * @see Context */ public interface SecurityContext { /** * String identifier for Basic authentication. Value "BASIC" */ public static final String BASIC_AUTH = "BASIC"; /** * String identifier for Client Certificate authentication. Value "CLIENT_CERT" */ public static final String CLIENT_CERT_AUTH = "CLIENT_CERT"; /** * String identifier for Digest authentication. Value "DIGEST" */ public static final String DIGEST_AUTH = "DIGEST"; /** * String identifier for Form authentication. Value "FORM" */ public static final String FORM_AUTH = "FORM"; /** * Returns a java.security.Principal object containing the * name of the current authenticated user. If the user * has not been authenticated, the method returns null. * * @return a java.security.Principal containing the name * of the user making this request; null if the user has not been * authenticated * @throws java.lang.IllegalStateException if called outside the scope of a request */ public Principal getUserPrincipal(); /** * Returns a boolean indicating whether the authenticated user is included * in the specified logical "role". If the user has not been authenticated, * the method returns false. * * @param role a String specifying the name of the role * @return a boolean indicating whether the user making * the request belongs to a given role; false if the user * has not been authenticated * @throws java.lang.IllegalStateException if called outside the scope of a request */ public boolean isUserInRole(String role); /** * Returns a boolean indicating whether this request was made * using a secure channel, such as HTTPS. * * @return true if the request was made using a secure * channel, false otherwise * @throws java.lang.IllegalStateException if called outside the scope of a request */ public boolean isSecure(); /** * Returns the string value of the authentication scheme used to protect * the resource. If the resource is not authenticated, null is returned. * * Values are the same as the CGI variable AUTH_TYPE * * @return one of the static members BASIC_AUTH, FORM_AUTH, * CLIENT_CERT_AUTH, DIGEST_AUTH (suitable for == comparison) or the * container-specific string indicating the authentication scheme, * or null if the request was not authenticated. * @throws java.lang.IllegalStateException if called outside the scope of a request */ public String getAuthenticationScheme(); } libjsr311-api-java-1.1.1/javax/ws/rs/core/StreamingOutput.java000066400000000000000000000026221136334242300240500ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * StreamingOutput.java * * Created on March 3, 2008, 4:00 PM * */ package javax.ws.rs.core; import java.io.IOException; import java.io.OutputStream; import javax.ws.rs.WebApplicationException; /** * A type that may be used as a resource method return value or as the entity * in a {@link Response} when the application wishes to stream the output. * This is a lightweight alternative to a * {@link javax.ws.rs.ext.MessageBodyWriter}. * * @see javax.ws.rs.ext.MessageBodyWriter * @see javax.ws.rs.core.Response */ public interface StreamingOutput { /** * Called to write the message body. * @param output the OutputStream to write to. * @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 any bytes being written to output. */ void write(OutputStream output) throws IOException, WebApplicationException; } libjsr311-api-java-1.1.1/javax/ws/rs/core/UriBuilder.java000066400000000000000000000513261136334242300227510ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * UriBuilder.java * * Created on July 18, 2007, 11:53 AM * */ package javax.ws.rs.core; import java.lang.reflect.Method; import java.net.URI; import java.util.Map; import javax.ws.rs.ext.RuntimeDelegate; /** * URI template aware utility class for building URIs from their components. See * {@link javax.ws.rs.Path#value} for an explanation of URI templates. * *

Builder methods perform contextual encoding of characters not permitted in * the corresponding URI component following the rules of the * application/x-www-form-urlencoded * media type for query parameters and * RFC 3986 for all other * components. Note that only characters not permitted in a particular component * are subject to encoding so, e.g., a path supplied to one of the {@code path} * methods may contain matrix parameters or multiple path segments since the * separators are legal characters and will not be encoded. Percent encoded * values are also recognized where allowed and will not be double encoded.

* *

URI templates are allowed in most components of a URI but their value is * restricted to a particular component. E.g. *

UriBuilder.fromPath("{arg1}").build("foo#bar");
* would result in encoding of the '#' such that the resulting URI is * "foo%23bar". To create a URI "foo#bar" use *
UriBuilder.fromPath("{arg1}").fragment("{arg2}").build("foo", "bar")
* instead. URI template names and delimiters are never encoded but their * values are encoded when a URI is built. * Template parameter regular expressions are ignored when building a URI, i.e. * no validation is performed. * * @see java.net.URI * @see javax.ws.rs.Path */ public abstract class UriBuilder { /** * Protected constructor, use one of the static fromXXX * methods to obtain an instance. */ protected UriBuilder() {} /** * Creates a new instance of UriBuilder. * @return a new instance of UriBuilder */ protected static UriBuilder newInstance() { UriBuilder b = RuntimeDelegate.getInstance().createUriBuilder(); return b; } /** * Create a new instance initialized from an existing URI. * @param uri a URI that will be used to initialize the UriBuilder. * @return a new UriBuilder * @throws IllegalArgumentException if uri is null */ public static UriBuilder fromUri(URI uri) throws IllegalArgumentException { UriBuilder b = newInstance(); b.uri(uri); return b; } /** * Create a new instance initialized from an existing URI. * @param uri a URI that will be used to initialize the UriBuilder, may not * contain URI parameters. * @return a new UriBuilder * @throws IllegalArgumentException if uri is not a valid URI or is null */ public static UriBuilder fromUri(String uri) throws IllegalArgumentException { URI u; try { u = URI.create(uri); } catch (NullPointerException ex) { throw new IllegalArgumentException(ex.getMessage(), ex); } return fromUri(u); } /** * Create a new instance representing a relative URI initialized from a * URI path. * @param path a URI path that will be used to initialize the UriBuilder, * may contain URI template parameters. * @return a new UriBuilder * @throws IllegalArgumentException if path is null */ public static UriBuilder fromPath(String path) throws IllegalArgumentException { UriBuilder b = newInstance(); b.path(path); return b; } /** * Create a new instance representing a relative URI initialized from a * root resource class. * * @param resource a root resource whose {@link javax.ws.rs.Path} value will * be used to initialize the UriBuilder. * @return a new UriBuilder * @throws IllegalArgumentException if resource is not annotated with * {@link javax.ws.rs.Path} or resource is null. */ public static UriBuilder fromResource(Class resource) throws IllegalArgumentException { UriBuilder b = newInstance(); b.path(resource); return b; } /** * Create a copy of the UriBuilder preserving its state. This is a more * efficient means of creating a copy than constructing a new UriBuilder * from a URI returned by the {@link #build} method. * @return a copy of the UriBuilder */ @Override public abstract UriBuilder clone(); /** * Copies the non-null components of the supplied URI to the UriBuilder replacing * any existing values for those components. * @param uri the URI to copy components from * @return the updated UriBuilder * @throws IllegalArgumentException if uri is null */ public abstract UriBuilder uri(URI uri) throws IllegalArgumentException; /** * Set the URI scheme. * @param scheme the URI scheme, may contain URI template parameters. * A null value will unset the URI scheme. * @return the updated UriBuilder * @throws IllegalArgumentException if scheme is invalid */ public abstract UriBuilder scheme(String scheme) throws IllegalArgumentException; /** * Set the URI scheme-specific-part (see {@link java.net.URI}). This * method will overwrite any existing * values for authority, user-info, host, port and path. * @param ssp the URI scheme-specific-part, may contain URI template parameters * @return the updated UriBuilder * @throws IllegalArgumentException if ssp cannot be parsed or is null */ public abstract UriBuilder schemeSpecificPart(String ssp) throws IllegalArgumentException; /** * Set the URI user-info. * @param ui the URI user-info, may contain URI template parameters. * A null value will unset userInfo component of the URI. * @return the updated UriBuilder */ public abstract UriBuilder userInfo(String ui); /** * Set the URI host. * @return the updated UriBuilder * @param host the URI host, may contain URI template parameters. * A null value will unset the host component of the URI. * @throws IllegalArgumentException if host is invalid. */ public abstract UriBuilder host(String host) throws IllegalArgumentException; /** * Set the URI port. * @param port the URI port, a value of -1 will unset an explicit port. * @return the updated UriBuilder * @throws IllegalArgumentException if port is invalid */ public abstract UriBuilder port(int port) throws IllegalArgumentException; /** * Set the URI path. This method will overwrite * any existing path and associated matrix parameters. * Existing '/' characters are preserved thus a single value can * represent multiple URI path segments. * @param path the path, may contain URI template parameters. * A null value will unset the path component of the URI. * @return the updated UriBuilder */ public abstract UriBuilder replacePath(String path); /** * Append path to the existing path. * When constructing the final path, a '/' separator will be inserted * between the existing path and the supplied path if necessary. * Existing '/' characters are preserved thus a single value can * represent multiple URI path segments. * @param path the path, may contain URI template parameters * @return the updated UriBuilder * @throws IllegalArgumentException if path is null */ public abstract UriBuilder path(String path) throws IllegalArgumentException; /** * Append the path from a Path-annotated class to the * existing path. * When constructing the final path, a '/' separator will be inserted * between the existing path and the supplied path if necessary. * * @param resource a resource whose {@link javax.ws.rs.Path} value will be * used to obtain the path to append. * @return the updated UriBuilder * @throws IllegalArgumentException if resource is null, or * if resource is not annotated with {@link javax.ws.rs.Path} */ public abstract UriBuilder path(Class resource) throws IllegalArgumentException; /** * Append the path from a Path-annotated method to the * existing path. * When constructing the final path, a '/' separator will be inserted * between the existing path and the supplied path if necessary. * This method is a convenience shortcut to path(Method), it * can only be used in cases where there is a single method with the * specified name that is annotated with {@link javax.ws.rs.Path}. * * @param resource the resource containing the method * @param method the name of the method whose {@link javax.ws.rs.Path} value will be * used to obtain the path to append * @return the updated UriBuilder * @throws IllegalArgumentException if resource or method is null, * or there is more than or less than one variant of the method annotated with * {@link javax.ws.rs.Path} */ public abstract UriBuilder path(Class resource, String method) throws IllegalArgumentException; /** * Append the path from a {@link javax.ws.rs.Path}-annotated method to the * existing path. * When constructing the final path, a '/' separator will be inserted * between the existing path and the supplied path if necessary. * * @param method a method whose {@link javax.ws.rs.Path} value will be * used to obtain the path to append to the existing path * @return the updated UriBuilder * @throws IllegalArgumentException if method is null or is * not annotated with a {@link javax.ws.rs.Path} */ public abstract UriBuilder path(Method method) throws IllegalArgumentException; /** * Append path segments to the existing path. * When constructing the final path, a '/' separator will be inserted * between the existing path and the first path segment if necessary and * each supplied segment will also be separated by '/'. * Existing '/' characters are encoded thus a single value can * only represent a single URI path segment. * @param segments the path segment values, each may contain URI template * parameters * @return the updated UriBuilder * @throws IllegalArgumentException if segments or any element of segments * is null */ public abstract UriBuilder segment(String... segments) throws IllegalArgumentException; /** * Set the matrix parameters of the current final segment of the current URI path. * This method will overwrite any existing matrix parameters on the current final * segment of the current URI path. Note that the matrix parameters * are tied to a particular path segment; subsequent addition of path segments * will not affect their position in the URI path. * @param matrix the matrix parameters, may contain URI template parameters. * A null value will remove all matrix parameters of the current final segment * of the current URI path. * @return the updated UriBuilder * @throws IllegalArgumentException if matrix cannot be parsed * @see Matrix URIs */ public abstract UriBuilder replaceMatrix(String matrix) throws IllegalArgumentException; /** * Append a matrix parameter to the existing set of matrix parameters of * the current final segment of the URI path. If multiple values are supplied * the parameter will be added once per value. Note that the matrix parameters * are tied to a particular path segment; subsequent addition of path segments * will not affect their position in the URI path. * @param name the matrix parameter name, may contain URI template parameters * @param values the matrix parameter value(s), each object will be converted * to a {@code String} using its {@code toString()} method. Stringified * values may contain URI template parameters. * @return the updated UriBuilder * @throws IllegalArgumentException if name or values is null * @see Matrix URIs */ public abstract UriBuilder matrixParam(String name, Object... values) throws IllegalArgumentException; /** * Replace the existing value(s) of a matrix parameter on * the current final segment of the URI path. If multiple values are supplied * the parameter will be added once per value. Note that the matrix parameters * are tied to a particular path segment; subsequent addition of path segments * will not affect their position in the URI path. * @param name the matrix parameter name, may contain URI template parameters * @param values the matrix parameter value(s), each object will be converted * to a {@code String} using its {@code toString()} method. Stringified * values may contain URI template parameters. If {@code values} is empty * or null then all current values of the parameter are removed. * @return the updated UriBuilder * @throws IllegalArgumentException if name is null. * @see Matrix URIs */ public abstract UriBuilder replaceMatrixParam(String name, Object... values) throws IllegalArgumentException; /** * Set the URI query string. This method will overwrite any existing query * parameters. * @param query the URI query string, may contain URI template parameters. * A null value will remove all query parameters. * @return the updated UriBuilder * @throws IllegalArgumentException if query cannot be parsed */ public abstract UriBuilder replaceQuery(String query) throws IllegalArgumentException; /** * Append a query parameter to the existing set of query parameters. If * multiple values are supplied the parameter will be added once per value. * @param name the query parameter name, may contain URI template parameters * @param values the query parameter value(s), each object will be converted * to a {@code String} using its {@code toString()} method. Stringified * values may contain URI template parameters. * @return the updated UriBuilder * @throws IllegalArgumentException if name or values is null */ public abstract UriBuilder queryParam(String name, Object... values) throws IllegalArgumentException; /** * Replace the existing value(s) of a query parameter. If * multiple values are supplied the parameter will be added once per value. * @param name the query parameter name, may contain URI template parameters * @param values the query parameter value(s), each object will be converted * to a {@code String} using its {@code toString()} method. Stringified * values may contain URI template parameters. If {@code values} is empty * or null then all current values of the parameter are removed. * @return the updated UriBuilder * @throws IllegalArgumentException if name is null */ public abstract UriBuilder replaceQueryParam(String name, Object... values) throws IllegalArgumentException; /** * Set the URI fragment. * @param fragment the URI fragment, may contain URI template parameters. * A null value will remove any existing fragment. * @return the updated UriBuilder */ public abstract UriBuilder fragment(String fragment); /** * Build a URI, any URI template parameters will be replaced by the value in * the supplied map. Values are converted to String using * their toString method and are then encoded to match the * rules of the URI component to which they pertain. All '%' characters * in the stringified values will be encoded. * The state of the builder is unaffected; this method may be called * multiple times on the same builder instance. * @param values a map of URI template parameter names and values * @return the URI built from the UriBuilder * @throws IllegalArgumentException if there are any URI template parameters * without a supplied value, or if a template parameter value is null. * @throws UriBuilderException if a URI cannot be constructed based on the * current state of the builder. */ public abstract URI buildFromMap(Map values) throws IllegalArgumentException, UriBuilderException; /** * Build a URI, any URI template parameters will be replaced by the value in * the supplied map. Values are converted to String using * their toString method and are then encoded to match the * rules of the URI component to which they pertain. All % characters in * the stringified values that are not followed by two hexadecimal numbers * will be encoded. * The state of the builder is unaffected; this method may be called * multiple times on the same builder instance. * @param values a map of URI template parameter names and values * @return the URI built from the UriBuilder * @throws IllegalArgumentException if there are any URI template parameters * without a supplied value, or if a template parameter value is null. * @throws UriBuilderException if a URI cannot be constructed based on the * current state of the builder. */ public abstract URI buildFromEncodedMap(Map values) throws IllegalArgumentException, UriBuilderException; /** * Build a URI, using the supplied values in order to replace any URI * template parameters. Values are converted to String using * their toString method and are then encoded to match the * rules of the URI component to which they pertain. All '%' characters * in the stringified values will be encoded. * The state of the builder is unaffected; this method may be called * multiple times on the same builder instance. *

All instances of the same template parameter * will be replaced by the same value that corresponds to the position of the * first instance of the template parameter. e.g. the template "{a}/{b}/{a}" * with values {"x", "y", "z"} will result in the the URI "x/y/x", not * "x/y/z". * @param values a list of URI template parameter values * @return the URI built from the UriBuilder * @throws IllegalArgumentException if there are any URI template parameters * without a supplied value, or if a value is null. * @throws UriBuilderException if a URI cannot be constructed based on the * current state of the builder. */ public abstract URI build(Object... values) throws IllegalArgumentException, UriBuilderException; /** * Build a URI. * Any URI templates parameters will be replaced with the supplied values in * order. Values are converted to String using * their toString method and are then encoded to match the * rules of the URI component to which they pertain. All % characters in * the stringified values that are not followed by two hexadecimal numbers * will be encoded. * The state of the builder is unaffected; this method may be called * multiple times on the same builder instance. *

All instances of the same template parameter * will be replaced by the same value that corresponds to the position of the * first instance of the template parameter. e.g. the template "{a}/{b}/{a}" * with values {"x", "y", "z"} will result in the the URI "x/y/x", not * "x/y/z". * @param values a list of URI template parameter values * @return the URI built from the UriBuilder * @throws IllegalArgumentException if there are any URI template parameters * without a supplied value, or if a value is null. * @throws UriBuilderException if a URI cannot be constructed based on the * current state of the builder. */ public abstract URI buildFromEncoded(Object... values) throws IllegalArgumentException, UriBuilderException; } libjsr311-api-java-1.1.1/javax/ws/rs/core/UriBuilderException.java000066400000000000000000000045551136334242300246320ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * UriBuilderException.java * * Created on August 22, 2007, 4:41 PM * */ package javax.ws.rs.core; /** * A runtime exception thrown by {@link UriBuilder#build} methods when a {@link * java.net.URI} cannot be constructed based on the current state of the * builder. */ public class UriBuilderException extends java.lang.RuntimeException { private static final long serialVersionUID = 956255913370721193L; /** * Creates a new instance of UriBuilderException without detail message. */ public UriBuilderException() { } /** * Constructs an instance of UriBuilderException with the specified detail message. * @param msg the detail message (which is saved for later retrieval by the Throwable.getMessage() method). */ public UriBuilderException(String msg) { super(msg); } /** * Constructs an instance of UriBuilderException with the specified detail message and cause. *

Note that the detail message associated with cause is not automatically incorporated in this exception's detail message. * @param msg the detail message (which is saved for later retrieval by the Throwable.getMessage() method). * @param cause the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.) */ public UriBuilderException(String msg, Throwable cause) { super(msg, cause); } /** * Constructs a new exception with the specified cause and a detail message * of (cause==null ? null : cause.toString()) (which typically contains * the class and detail message of cause). This constructor is useful * for exceptions that are little more than wrappers for other throwables. * @param cause the original exception */ public UriBuilderException(Throwable cause) { super(cause); } } libjsr311-api-java-1.1.1/javax/ws/rs/core/UriInfo.java000066400000000000000000000255761136334242300222660ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * UriInfo.java * * Created on April 13, 2007, 2:55 PM * */ package javax.ws.rs.core; import java.net.URI; import java.util.List; /** * An injectable interface that provides access to application and request * URI information. Relative URIs are relative to the base URI of the * application, see {@link #getBaseUri}. * *

All methods throw java.lang.IllegalStateException * if called outside the scope of a request (e.g. from a provider constructor).

* * @see Context */ public interface UriInfo { /** * Get the path of the current request relative to the base URI as * a string. All sequences of escaped octets are decoded, equivalent to * getPath(true). * * @return the relative URI path * @throws java.lang.IllegalStateException if called outside the scope of a request */ public String getPath(); /** * Get the path of the current request relative to the base URI as * a string. * * @param decode controls whether sequences of escaped octets are decoded * (true) or not (false). * @return the relative URI path * @throws java.lang.IllegalStateException if called outside the scope of a request */ public String getPath(boolean decode); /** * Get the path of the current request relative to the base URI as a * 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 parameter values are decoded, * equivalent to getPathSegments(true). * @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 * @see PathSegment * @see Matrix URIs */ public List getPathSegments(); /** * Get the path of the current request relative to the base URI as a * 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. * @param decode controls whether sequences of escaped octets in path segments * 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 * @see PathSegment * @see Matrix URIs */ public List getPathSegments(boolean decode); /** * 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 */ public URI getRequestUri(); /** * Get the absolute request URI in the form of a UriBuilder. * @return a UriBuilder initialized with the absolute request URI * @throws java.lang.IllegalStateException if called outside the scope of a request */ public UriBuilder getRequestUriBuilder(); /** * Get the absolute path of the request. This includes everything preceding * the path (host, port etc) but excludes query parameters. * This is a shortcut for * uriInfo.getBase().resolve(uriInfo.getPath()). * @return the absolute path of the request * @throws java.lang.IllegalStateException if called outside the scope of a request */ public URI getAbsolutePath(); /** * 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. * @return a UriBuilder initialized with the absolute path of the request * @throws java.lang.IllegalStateException if called outside the scope of a request */ public UriBuilder getAbsolutePathBuilder(); /** * Get the base URI of the application. URIs of root resource classes * are all relative to this base URI. * @return the base URI of the application */ public URI getBaseUri(); /** * Get the base URI of the application in the form of a UriBuilder. * @return a UriBuilder initialized with the base URI of the application. */ public UriBuilder getBaseUriBuilder(); /** * Get the values of any embedded URI template parameters. * All sequences of escaped octets are decoded, * equivalent to getPathParameters(true). * @return an unmodifiable map of parameter names and values * @throws java.lang.IllegalStateException if called outside the scope of a request * @see javax.ws.rs.Path * @see javax.ws.rs.PathParam */ public MultivaluedMap getPathParameters(); /** * Get the values of any embedded URI template parameters. * * @param decode controls whether sequences of escaped octets are decoded * (true) or not (false). * @return an unmodifiable map of parameter names and values * @throws java.lang.IllegalStateException if called outside the scope of a request * @see javax.ws.rs.Path * @see javax.ws.rs.PathParam */ public MultivaluedMap getPathParameters(boolean decode); /** * Get the URI query parameters of the current request. * 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 getQueryParameters(true). * @return an unmodifiable map of query parameter names and values * @throws java.lang.IllegalStateException if called outside the scope of a request */ public MultivaluedMap getQueryParameters(); /** * 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 * 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 */ public MultivaluedMap getQueryParameters(boolean decode); /** * Get a read-only list of URIs for matched resources. Each entry is a * relative URI that matched a resource class, a * sub-resource method or a sub-resource locator. All sequences of escaped * octets are decoded, equivalent to {@code getMatchedURIs(true)}. * Entries do not include query parameters but do include matrix parameters * if present in the request URI. Entries are ordered in reverse request * URI matching order, with the current resource URI first. E.g. given the * following resource classes: * *
@Path("foo")
     *public class FooResource {
     *  @GET
     *  public String getFoo() {...}
     * 
     *  @Path("bar")
     *  public BarResource getBarResource() {...}
     *}
     * 
     *public class BarResource {
     *  @GET
     *  public String getBar() {...}
     *}
     * 
* *

The values returned by this method based on request uri and where * the method is called from are:

* * * * * * * * * * * * * * * * * * * * * * *
RequestCalled fromValue(s)
GET /fooFooResource.getFoofoo
GET /foo/barFooResource.getBarResourcefoo/bar, foo
GET /foo/barBarResource.getBarfoo/bar, foo
* * * @return a read-only list of URI paths for matched resources. */ public List getMatchedURIs(); /** * Get a read-only list of URIs for matched resources. Each entry is a * relative URI that matched a resource class, a sub-resource * method or a sub-resource locator. Entries do not include query * parameters but do include matrix parameters if present in the request URI. * Entries are ordered in reverse request URI matching order, with the * current resource URI first. See {@link #getMatchedURIs()} for an * example. * * @param decode controls whether sequences of escaped octets are decoded * (true) or not (false). * @return a read-only list of URI paths for matched resources. */ public List getMatchedURIs(boolean decode); /** * Get a read-only list of the currently matched resource class instances. * Each entry is a resource class instance that matched the request URI * either directly or via a sub-resource method or a sub-resource locator. * Entries are ordered according to reverse request URI matching order, * with the current resource first. E.g. given the following resource * classes: * *
@Path("foo")
     *public class FooResource {
     *  @GET
     *  public String getFoo() {...}
     * 
     *  @Path("bar")
     *  public BarResource getBarResource() {...}
     *}
     * 
     *public class BarResource {
     *  @GET
     *  public String getBar() {...}
     *}
     * 
* *

The values returned by this method based on request uri and where * the method is called from are:

* * * * * * * * * * * * * * * * * * * * * * *
RequestCalled fromValue(s)
GET /fooFooResource.getFooFooResource
GET /foo/barFooResource.getBarResourceFooResource
GET /foo/barBarResource.getBarBarResource, FooResource
* * @return a read-only list of matched resource class instances. */ public List getMatchedResources(); } libjsr311-api-java-1.1.1/javax/ws/rs/core/Variant.java000066400000000000000000000177511136334242300223130ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Variant.java * * Created on September 27, 2007, 3:12 PM * */ package javax.ws.rs.core; import java.io.StringWriter; import java.util.List; import java.util.Locale; import javax.ws.rs.ext.RuntimeDelegate; /** * Abstraction for a resource representation variant. */ public class Variant { private Locale language; private MediaType mediaType; private String encoding; /** * Create a new instance of Variant * @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) { if (mediaType==null && language==null && encoding==null) throw new IllegalArgumentException("mediaType, language, encoding all null"); this.encoding = encoding; this.language = language; this.mediaType = mediaType; } /** * Get the language of the variant * @return the language or null if none set */ public Locale getLanguage() { return language; } /** * Get the media type of the variant * @return the media type or null if none set */ public MediaType getMediaType() { return mediaType; } /** * Get the encoding of the variant * @return the encoding or null if none set */ public String getEncoding() { return encoding; } /** * Create a {@link VariantListBuilder} initialized with a set of supported * media types. * @param mediaTypes the available mediaTypes. If specific charsets * 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(); b.mediaTypes(mediaTypes); return b; } /** * Create a {@link VariantListBuilder} initialized with a set of supported * 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(); b.languages(languages); return b; } /** * Create a {@link VariantListBuilder} initialized with a set of supported * 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(); b.encodings(encodings); return b; } /** * Generate hash code from variant properties. * @return the hash code */ @Override public int hashCode() { int hash = 7; hash = 29 * hash + (this.language != null ? this.language.hashCode() : 0); hash = 29 * hash + (this.mediaType != null ? this.mediaType.hashCode() : 0); hash = 29 * hash + (this.encoding != null ? this.encoding.hashCode() : 0); return hash; } /** * Compares obj to this variant to see if they are the same * considering all property values. * @param obj the object to compare to * @return true if the two variants are the same, false otherwise. */ @Override public boolean equals(Object obj) { if (obj == null) { return false; } if (getClass() != obj.getClass()) { return false; } final Variant other = (Variant) obj; if (this.language != other.language && (this.language == null || !this.language.equals(other.language))) { return false; } if (this.mediaType != other.mediaType && (this.mediaType == null || !this.mediaType.equals(other.mediaType))) { return false; } if (this.encoding != other.encoding && (this.encoding == null || !this.encoding.equals(other.encoding))) { return false; } return true; } @Override public String toString() { StringWriter w = new StringWriter(); w.append("Variant[mediaType="); w.append(mediaType==null ? "null" : mediaType.toString()); w.append(", language="); w.append(language==null ? "null" : language.toString()); w.append(", encoding="); w.append(encoding==null ? "null" : encoding); w.append("]"); return w.toString(); } /** * A builder for a list of representation variants. */ public static abstract class VariantListBuilder { /** * Protected constructor, use the static newInstance * method to obtain an instance. */ protected VariantListBuilder() {} /** * Create a new builder instance. * @return a new Builder */ public static VariantListBuilder newInstance() { VariantListBuilder b = RuntimeDelegate.getInstance().createVariantListBuilder(); return b; } /** * Build a list of representation variants from the current state of * the builder. After this method is called the builder is reset to * an empty state. * @return a list of representation variants */ public abstract List build(); /** * Add the current combination of metadata to the list of supported variants, * after this method is called the current combination of metadata is emptied. * If more than one value is supplied for one or more of the variant properties * then a variant will be generated for each possible combination. E.g. * in the following list would have four members: *

List list = VariantListBuilder.newInstance().languages("en","fr")
         *   .encodings("zip", "identity").add().build()
* * @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(); /** * Set the language[s] for this variant. * @param languages the available languages * @return the updated builder */ public abstract VariantListBuilder languages(Locale... languages); /** * Set the encoding[s] for this variant. * @param encodings the available encodings * @return the updated builder */ public abstract VariantListBuilder encodings(String... encodings); /** * Set the media type[s] for this variant. * @param mediaTypes the available mediaTypes. If specific charsets * are supported they should be included as parameters of the respective * media type. * @return the updated builder */ public abstract VariantListBuilder mediaTypes(MediaType... mediaTypes); } } libjsr311-api-java-1.1.1/javax/ws/rs/core/package-info.java000066400000000000000000000001661136334242300232230ustar00rootroot00000000000000/** * Low-level interfaces and annotations used to create RESTful service * resources. */ package javax.ws.rs.core;libjsr311-api-java-1.1.1/javax/ws/rs/ext/000077500000000000000000000000001136334242300177015ustar00rootroot00000000000000libjsr311-api-java-1.1.1/javax/ws/rs/ext/ContextResolver.java000066400000000000000000000025311136334242300237130ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ package javax.ws.rs.ext; /** * Contract for a provider that supplies context information to resource * classes and other providers. An implementation of this interface must be * annotated with {@link Provider}. * * A ContextResolver implementation may be annotated * with {@link javax.ws.rs.Produces} to restrict the media types for * which it will be considered suitable. * * @see javax.ws.rs.core.Context * @see Providers#getContextResolver(java.lang.Class, javax.ws.rs.core.MediaType) * @see Provider * @see javax.ws.rs.Produces */ public interface ContextResolver { /** * Get a context of type T that is applicable to the supplied * type. * @param type the class of object for which a context is desired * @return a context for the supplied type or null if a * context for the supplied type is not available from this provider. */ T getContext(Class type); } libjsr311-api-java-1.1.1/javax/ws/rs/ext/ExceptionMapper.java000066400000000000000000000023241136334242300236500ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ package javax.ws.rs.ext; import javax.ws.rs.core.Response; /** * Contract for a provider that maps Java exceptions to * {@link javax.ws.rs.core.Response}. An implementation of this interface must * be annotated with {@link Provider}. * * @see Provider * @see javax.ws.rs.core.Response */ public interface ExceptionMapper { /** * Map an exception to a {@link javax.ws.rs.core.Response}. Returning * {@code null} results in a {@link javax.ws.rs.core.Response.Status#NO_CONTENT} * response. Throwing a runtime exception results in a * {@link javax.ws.rs.core.Response.Status#INTERNAL_SERVER_ERROR} response * @param exception the exception to map to a response * @return a response mapped from the supplied exception */ Response toResponse(E exception); } libjsr311-api-java-1.1.1/javax/ws/rs/ext/FactoryFinder.java000066400000000000000000000127021136334242300233050ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * FactoryFinder.java * * Created on November 16, 2007, 3:14 PM * */ package javax.ws.rs.ext; import java.io.BufferedReader; import java.io.File; import java.io.FileInputStream; import java.io.InputStream; import java.io.InputStreamReader; import java.security.AccessController; import java.security.PrivilegedAction; import java.util.Properties; class FactoryFinder { static ClassLoader getContextClassLoader() { return AccessController.doPrivileged( new PrivilegedAction() { public ClassLoader run() { ClassLoader cl = null; try { cl = Thread.currentThread().getContextClassLoader(); } catch (SecurityException ex) { } return cl; } }); } /** * Creates an instance of the specified class using the specified * ClassLoader object. * * @exception ClassNotFoundException if the given class could not be found * or could not be instantiated */ private static Object newInstance(String className, ClassLoader classLoader) throws ClassNotFoundException { try { Class spiClass; if (classLoader == null) { spiClass = Class.forName(className); } else { try { spiClass = Class.forName(className, false, classLoader); } catch (ClassNotFoundException ex) { spiClass = Class.forName(className); } } return spiClass.newInstance(); } catch (ClassNotFoundException x) { throw x; } catch (Exception x) { throw new ClassNotFoundException( "Provider " + className + " could not be instantiated: " + x, x); } } /** * Finds the implementation Class object for the given * factory name, or if that fails, finds the Class object * for the given fallback class name. The arguments supplied MUST be * used in order. If using the first argument is successful, the second * one will not be used. *

* This method is package private so that this code can be shared. * * @return the Class object of the specified message factory; * may not be null * * @param factoryId the name of the factory to find, which is * a system property * @param fallbackClassName the implementation class name, which is * to be used only if nothing else * is found; null to indicate that * there is no fallback class name * @exception WebServiceException if there is an error */ static Object find(String factoryId, String fallbackClassName) throws ClassNotFoundException { ClassLoader classLoader = getContextClassLoader(); String serviceId = "META-INF/services/" + factoryId; // try to find services in CLASSPATH try { InputStream is; if (classLoader == null) { is = ClassLoader.getSystemResourceAsStream(serviceId); } else { is = classLoader.getResourceAsStream(serviceId); } if (is != null) { BufferedReader rd = new BufferedReader(new InputStreamReader(is, "UTF-8")); String factoryClassName = rd.readLine(); rd.close(); if (factoryClassName != null && !"".equals(factoryClassName)) { return newInstance(factoryClassName, classLoader); } } } catch (Exception ex) { } // try to read from $java.home/lib/jaxrs.properties try { String javah = System.getProperty("java.home"); String configFile = javah + File.separator + "lib" + File.separator + "jaxrs.properties"; File f = new File(configFile); if (f.exists()) { Properties props = new Properties(); props.load(new FileInputStream(f)); String factoryClassName = props.getProperty(factoryId); return newInstance(factoryClassName, classLoader); } } catch (Exception ex) { } // Use the system property try { String systemProp = System.getProperty(factoryId); if (systemProp != null) { return newInstance(systemProp, classLoader); } } catch (SecurityException se) { } if (fallbackClassName == null) { throw new ClassNotFoundException( "Provider for " + factoryId + " cannot be found", null); } return newInstance(fallbackClassName, classLoader); } } libjsr311-api-java-1.1.1/javax/ws/rs/ext/MessageBodyReader.java000066400000000000000000000105371136334242300240770ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * MessageBodyReader.java * * Created on November 8, 2007, 3:57 PM * */ package javax.ws.rs.ext; import java.io.IOException; import java.io.InputStream; import java.lang.annotation.Annotation; import java.lang.reflect.Type; import javax.ws.rs.WebApplicationException; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MultivaluedMap; /** * Contract for a provider that supports the conversion of a stream to a * Java type. To add a MessageBodyReader implementation, annotate the * implementation class with @Provider. * * A MessageBodyReader implementation may be annotated * with {@link javax.ws.rs.Consumes} to restrict the media types for which it will * be considered suitable. * * @see Provider * @see javax.ws.rs.Consumes */ public interface MessageBodyReader { /** * Ascertain if the MessageBodyReader can produce an instance of a * particular type. The type parameter gives the * class of the object that should be produced, the genericType parameter * gives the java.lang.reflect.Type of the object that should be produced. * E.g. if the object to be produced is List, the type parameter * will be java.util.List and the genericType parameter will be * java.lang.reflect.ParameterizedType. * * @param type the class of object to be produced. * @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 * the formal type of the method parameter as returned by * Method.getGenericParameterTypes. * @param annotations an array of the annotations on the declaration of the * artifact that will be initialized with the produced instance. E.g. if the * message body is to be converted into a method parameter, this will be * the annotations on that parameter returned by * Method.getParameterAnnotations. * @param mediaType the media type of the HTTP entity, if one is not * specified in the request then application/octet-stream is * used. * @return true if the type is supported, otherwise false. */ boolean isReadable(Class type, Type genericType, Annotation annotations[], MediaType mediaType); /** * Read a type from the {@link InputStream}. * * @return the type that was read from the stream. * @param type the type that is to be read from the entity stream. * @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 * the formal type of the method parameter as returned by * Method.getGenericParameterTypes. * @param annotations an array of the annotations on the declaration of the * artifact that will be initialized with the produced instance. E.g. if the * message body is to be converted into a method parameter, this will be * the annotations on that parameter returned by * Method.getParameterAnnotations. * @param mediaType the media type of the HTTP entity. * @param httpHeaders the read-only HTTP headers associated with HTTP entity. * @param entityStream the {@link InputStream} of the HTTP entity. The * caller is responsible for ensuring that the input stream ends when the * entity has been consumed. The implementation should not close the input stream. * @throws java.io.IOException if an IO error arises * @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. */ T readFrom(Class type, Type genericType, Annotation annotations[], MediaType mediaType, MultivaluedMap httpHeaders, InputStream entityStream) throws IOException, WebApplicationException; } libjsr311-api-java-1.1.1/javax/ws/rs/ext/MessageBodyWriter.java000066400000000000000000000107441136334242300241510ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * MessageBodyWriter.java * * Created on November 8, 2007, 3:57 PM * */ package javax.ws.rs.ext; import java.io.IOException; import java.io.OutputStream; import java.lang.annotation.Annotation; import java.lang.reflect.Type; import javax.ws.rs.WebApplicationException; import javax.ws.rs.core.MediaType; import javax.ws.rs.core.MultivaluedMap; /** * Contract for a provider that supports the conversion of a Java type to a * stream. To add a MessageBodyWriter implementation, annotate the * implementation class with @Provider. * * A MessageBodyWriter implementation may be annotated * with {@link javax.ws.rs.Produces} to restrict the media types for which it will * be considered suitable. * * @param T the type that can be written * @see Provider * @see javax.ws.rs.Produces */ public interface MessageBodyWriter { /** * Ascertain if the MessageBodyWriter supports a particular type. * * @param type the class of object that is to be written. * @param genericType the type of object to be written, obtained either * by reflection of a resource method return type or via inspection * of the returned instance. {@link javax.ws.rs.core.GenericEntity} * provides a way to specify this information at runtime. * @param annotations an array of the annotations on the resource * method that returns the object. * @param mediaType the media type of the HTTP entity. * @return true if the type is supported, otherwise false. */ boolean isWriteable(Class type, Type genericType, Annotation annotations[], MediaType mediaType); /** * Called before writeTo to ascertain the length in bytes of * the serialized form of t. A non-negative return value is * used in a HTTP Content-Length header. * @param t the instance to write * @param type the class of object that is to be written. * @param genericType the type of object to be written, obtained either * by reflection of a resource method return type or by inspection * of the returned instance. {@link javax.ws.rs.core.GenericEntity} * provides a way to specify this information at runtime. * @param annotations an array of the annotations on the resource * method that returns the object. * @param mediaType the media type of the HTTP entity. * @return length in bytes or -1 if the length cannot be determined in * advance */ long getSize(T t, Class type, Type genericType, Annotation annotations[], MediaType mediaType); /** * Write a type to an HTTP response. The response header map is mutable * but any changes must be made before writing to the output stream since * the headers will be flushed prior to writing the response body. * * @param t the instance to write. * @param type the class of object that is to be written. * @param genericType the type of object to be written, obtained either * by reflection of a resource method return type or by inspection * of the returned instance. {@link javax.ws.rs.core.GenericEntity} * provides a way to specify this information at runtime. * @param annotations an array of the annotations on the resource * method that returns the object. * @param mediaType the media type of the HTTP entity. * @param httpHeaders a mutable map of the HTTP response headers. * @param entityStream the {@link OutputStream} for the HTTP entity. The * implementation should not close the output stream. * @throws java.io.IOException if an IO error arises * @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. */ void writeTo(T t, Class type, Type genericType, Annotation annotations[], MediaType mediaType, MultivaluedMap httpHeaders, OutputStream entityStream) throws IOException, WebApplicationException; } libjsr311-api-java-1.1.1/javax/ws/rs/ext/Provider.java000066400000000000000000000017231136334242300223410ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Provider.java * * Created on May 15, 2007, 11:59 AM * */ package javax.ws.rs.ext; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Marks an implementation of an extension interface. * * @see MessageBodyReader * @see MessageBodyWriter * @see ContextResolver * @see ExceptionMapper */ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface Provider { } libjsr311-api-java-1.1.1/javax/ws/rs/ext/Providers.java000066400000000000000000000140021136334242300225160ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * Providers.java * * Created on March 5, 2008, 9:00 AM * */ package javax.ws.rs.ext; import java.lang.annotation.Annotation; import java.lang.reflect.Type; import javax.ws.rs.core.MediaType; /** * An injectable interface providing runtime lookup of provider instances. * * @see javax.ws.rs.core.Context * @see MessageBodyReader * @see MessageBodyWriter * @see ContextResolver * @see ExceptionMapper */ public interface Providers { /** * 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}, 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 * {@link MessageBodyReader#isReadable} * 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 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 * the formal type of the method parameter as returned by * Class.getGenericParameterTypes. * @param annotations an array of the annotations on the declaration of the * artifact that will be initialized with the produced instance. E.g. if the * message body is to be converted into a method parameter, this will be * the annotations on that parameter returned by * Class.getParameterAnnotations. * @param mediaType the media type of the data that will be read. * @return a MessageBodyReader that matches the supplied criteria or null * if none is found. */ MessageBodyReader getMessageBodyReader(Class type, Type genericType, Annotation annotations[], MediaType mediaType); /** * 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}, 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 * {@link MessageBodyWriter#isWriteable} * method is called on each writer in order using the supplied criteria and * the first writer that returns {@code true} is selected and returned. * * @param type the class of object that is to be written. * @param genericType the type of object to be written. E.g. if the * message body is to be produced from a field, this will be * the declared type of the field as returned by * Field.getGenericType. * @param annotations an array of the annotations on the declaration of the * artifact that will be written. E.g. if the * message body is to be produced from a field, this will be * the annotations on that field returned by * Field.getDeclaredAnnotations. * @param mediaType the media type of the data that will be written. * @return a MessageBodyReader that matches the supplied criteria or null * if none is found. */ MessageBodyWriter getMessageBodyWriter(Class type, Type genericType, Annotation annotations[], MediaType mediaType); /** * Get an exception mapping provider for a particular class of exception. * Returns the provider whose generic type is the nearest superclass of * {@code type}. * @param type the class of exception * @return an {@link ExceptionMapper} for the supplied type or null if none * is found. */ ExceptionMapper getExceptionMapper(Class type); /** * 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}, 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 * resolver in order and returns the first non-null value it obtains or null * if all matching context resolvers return null. * * @param contextType the class of context desired * @param mediaType the media type of data for which a context is required. * @return a matching context resolver instance or null if no matching * context providers are found. */ ContextResolver getContextResolver(Class contextType, MediaType mediaType); } libjsr311-api-java-1.1.1/javax/ws/rs/ext/RuntimeDelegate.java000066400000000000000000000207621136334242300236310ustar00rootroot00000000000000/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * http://www.opensource.org/licenses/cddl1.php * See the License for the specific language governing * permissions and limitations under the License. */ /* * RuntimeDelegate.java * * Created on November 15, 2007, 4:00 PM * */ package javax.ws.rs.ext; import java.lang.reflect.ReflectPermission; import java.net.URL; import javax.ws.rs.core.Application; import javax.ws.rs.core.Response.ResponseBuilder; import javax.ws.rs.core.Variant.VariantListBuilder; import javax.ws.rs.core.UriBuilder; /** * Implementations of JAX-RS provide a concrete subclass of RuntimeDelegate and * various JAX-RS API methods defer to methods of RuntimeDelegate for their * functionality. Regular users of JAX-RS are not expected to use this class * directly and overriding an implementation of this class with a user supplied * subclass may cause unexpected behavior. * */ public abstract class RuntimeDelegate { public static final String JAXRS_RUNTIME_DELEGATE_PROPERTY = "javax.ws.rs.ext.RuntimeDelegate"; private static final String JAXRS_DEFAULT_RUNTIME_DELEGATE = "com.sun.ws.rs.ext.RuntimeDelegateImpl"; private static ReflectPermission rp = new ReflectPermission("suppressAccessChecks"); protected RuntimeDelegate() { } private static volatile RuntimeDelegate rd; /** * Obtain a RuntimeDelegate instance. If an instance had not already been * created and set via {@link #setInstance}, the first invocation will * create an instance which will then be cached for future use. * *

* The algorithm used to locate the RuntimeDelegate subclass to use consists * of the following steps: *

*

    *
  • * If a resource with the name of * META-INF/services/javax.ws.rs.ext.RuntimeDelegate * exists, then its first line, if present, is used as the UTF-8 encoded * name of the implementation class. *
  • *
  • * If the $java.home/lib/jaxrs.properties file exists and it is readable by * the java.util.Properties.load(InputStream) method and it contains * an entry whose key is javax.ws.rs.ext.RuntimeDelegate, then the value of * that entry is used as the name of the implementation class. *
  • *
  • * If a system property with the name javax.ws.rs.ext.RuntimeDelegate * is defined, then its value is used as the name of the implementation class. *
  • *
  • * Finally, a default implementation class name is used. *
  • *
* * @return an instance of RuntimeDelegate */ public static RuntimeDelegate getInstance() { // Double-check idiom for lazy initialization of fields. RuntimeDelegate result = rd; if (result == null) { // First check (no locking) synchronized(RuntimeDelegate.class) { result = rd; if (result == null) { // Second check (with locking) rd = result = findDelegate(); } } } return result; } /** * Obtain a RuntimeDelegate instance using the method described in * {@link #getInstance}. * @return an instance of RuntimeDelegate */ private static RuntimeDelegate findDelegate() { try { Object delegate = FactoryFinder.find(JAXRS_RUNTIME_DELEGATE_PROPERTY, JAXRS_DEFAULT_RUNTIME_DELEGATE); if (!(delegate instanceof RuntimeDelegate)) { Class pClass = RuntimeDelegate.class; String classnameAsResource = pClass.getName().replace('.', '/') + ".class"; ClassLoader loader = pClass.getClassLoader(); if(loader == null) { loader = ClassLoader.getSystemClassLoader(); } URL targetTypeURL = loader.getResource(classnameAsResource); throw new LinkageError("ClassCastException: attempting to cast" + delegate.getClass().getClassLoader().getResource(classnameAsResource) + "to" + targetTypeURL.toString() ); } return (RuntimeDelegate) delegate; } catch (Exception ex) { throw new RuntimeException(ex); } } /** * Set the runtime delegate that will be used by JAX-RS classes. If this method * is not called prior to {@link #getInstance} then an implementation will * be sought as described in {@link #getInstance}. * @param rd the runtime delegate instance * @throws SecurityException if there is a security manager and the permission * ReflectPermission("suppressAccessChecks") has not been granted. */ public static void setInstance(RuntimeDelegate rd) throws SecurityException { SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkPermission(rp); } synchronized(RuntimeDelegate.class) { RuntimeDelegate.rd = rd; } } /** * Create a new instance of a {@link javax.ws.rs.core.UriBuilder}. * @return new UriBuilder instance * @see javax.ws.rs.core.UriBuilder */ public abstract UriBuilder createUriBuilder(); /** * Create a new instance of a {@link javax.ws.rs.core.Response.ResponseBuilder}. * @return new ResponseBuilder instance * @see javax.ws.rs.core.Response.ResponseBuilder */ public abstract ResponseBuilder createResponseBuilder(); /** * Create a new instance of a {@link javax.ws.rs.core.Variant.VariantListBuilder}. * * @return new VariantListBuilder instance * @see javax.ws.rs.core.Variant.VariantListBuilder */ public abstract VariantListBuilder createVariantListBuilder(); /** * Create a configured instance of the supplied endpoint type. How the * returned endpoint instance is published is dependent on the type of * endpoint. * @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 application is null or the * requested endpoint type is not supported. * @throws java.lang.UnsupportedOperationException if the implementation * supports no endpoint types. */ public abstract T createEndpoint(Application application, Class endpointType) throws IllegalArgumentException, UnsupportedOperationException; /** * Obtain an instance of a HeaderDelegate for the supplied class. An * implementation is required to support the following values for type: * {@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 HeaderDelegate createHeaderDelegate(Class type); /** * Defines the contract for a delegate that is responsible for * converting between the String form of a HTTP header and * the corresponding JAX-RS type T. * @param T a JAX-RS type that corresponds to the value of a HTTP header */ public static interface HeaderDelegate { /** * Parse the supplied value and create an instance of T. * @param value the string value * @return the newly created instance of T * @throws IllegalArgumentException if the supplied string cannot be * parsed or is null */ public T fromString(String value) throws IllegalArgumentException; /** * Convert the supplied value to a String. * @param value the value of type T * @return a String representation of the value * @throws IllegalArgumentException if the supplied object cannot be * serialized or is null */ public String toString(T value); } } libjsr311-api-java-1.1.1/javax/ws/rs/ext/package-info.java000066400000000000000000000001521136334242300230660ustar00rootroot00000000000000/** * APIs that provide extensions to the types supported by the JAX-RS API. */ package javax.ws.rs.ext;libjsr311-api-java-1.1.1/javax/ws/rs/package-info.java000066400000000000000000000010461136334242300222710ustar00rootroot00000000000000/** * High-level interfaces and annotations used to create RESTful service * resources. E.g.:
@Path("widgets/{widgetid}")
@Consumes("application/widgets+xml")
@Produces("application/widgets+xml")
public class WidgetResource {

  @GET
  public String getWidget(@PathParam("widgetid") String id) {
    return getWidgetAsXml(id);
  }
  
  @PUT
  public void updateWidget(@PathParam("widgetid") String id,
    Source update) {
    updateWidgetFromXml(id, update);
  }
  
  ...
}
*/ package javax.ws.rs;