001 /*
002 * The contents of this file are subject to the terms
003 * of the Common Development and Distribution License
004 * (the "License"). You may not use this file except
005 * in compliance with the License.
006 *
007 * You can obtain a copy of the license at
008 * http://www.opensource.org/licenses/cddl1.php
009 * See the License for the specific language governing
010 * permissions and limitations under the License.
011 */
012
013 /*
014 * PathParam.java
015 *
016 * Created on November 16, 2006, 2:04 PM
017 *
018 */
019 package javax.ws.rs;
020
021 import java.lang.annotation.ElementType;
022 import java.lang.annotation.Retention;
023 import java.lang.annotation.RetentionPolicy;
024 import java.lang.annotation.Target;
025
026 /**
027 * Binds the value of a URI template parameter or a path segment
028 * containing the template parameter to a resource method parameter, resource
029 * class field, or resource class
030 * bean property. The value is URL decoded unless this
031 * is disabled using the {@link Encoded} annotation.
032 * A default value can be specified using the {@link DefaultValue}
033 * annotation.
034 *
035 * The type of the annotated parameter, field or property must either:
036 * <ul>
037 * <li>Be {@link javax.ws.rs.core.PathSegment}, the value will be the final
038 * segment of the matching part of the path.
039 * See {@link javax.ws.rs.core.UriInfo} for a means of retrieving all request
040 * path segments.</li>
041 * <li>Be {@code List<}{@link javax.ws.rs.core.PathSegment}{@code >}, the
042 * value will be a list of {@code PathSegment} corresponding to the path
043 * segment(s) that matched the named template parameter.
044 * See {@link javax.ws.rs.core.UriInfo} for a means of retrieving all request
045 * path segments.</li>
046 * <li>Be a primitive type.</li>
047 * <li>Have a constructor that accepts a single String argument.</li>
048 * <li>Have a static method named <code>valueOf</code> or <code>fromString</code>
049 * that accepts a single
050 * String argument (see, for example, {@link Integer#valueOf(String)}).
051 * </ul>
052 *
053 * <p>The injected value corresponds to the latest use (in terms of scope) of
054 * the path parameter. E.g. if a class and a sub-resource method are both
055 * annotated with a {@link Path} containing the same URI template parameter, use
056 * of {@code PathParam} on a subresource method parameter will bind the value
057 * matching URI template parameter in the method's {@link Path} annotation.</p>
058 *
059 * <p>Because injection occurs at object creation time, use of this annotation
060 * on resource class fields and bean properties is only supported for the
061 * default per-request resource class lifecycle. Resource classes using
062 * other lifecycles should only use this annotation on resource method
063 * parameters.</p>
064 *
065 * @see Encoded
066 * @see DefaultValue
067 * @see javax.ws.rs.core.PathSegment
068 * @see javax.ws.rs.core.UriInfo
069 */
070 @Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.FIELD})
071 @Retention(RetentionPolicy.RUNTIME)
072 public @interface PathParam {
073 /**
074 * Defines the name of the URI template parameter whose value will be used
075 * to initialize the value of the annotated method parameter, class field or
076 * property. See {@link Path#value()} for a description of the syntax of
077 * template parameters.
078 *
079 * <p>E.g. a class annotated with: <code>@Path("widgets/{id}")</code>
080 * can have methods annotated whose arguments are annotated
081 * with <code>@PathParam("id")</code>.
082 */
083 String value();
084 }