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     * Path.java
015     *
016     * Created on September 15, 2006, 2:33 PM
017     *
018     */
019    
020    package javax.ws.rs;
021    
022    import java.lang.annotation.ElementType;
023    import java.lang.annotation.Retention;
024    import java.lang.annotation.RetentionPolicy;
025    import java.lang.annotation.Target;
026    
027    /**
028     * Identifies the URI path that a resource class or class method will serve 
029     * requests for.
030     *
031     * <p>Paths are relative. For an annotated class the base URI is the 
032     * application path, see {@link javax.ws.rs.ApplicationPath}. For an annotated
033     * method the base URI is the
034     * effective URI of the containing class. For the purposes of absolutizing a
035     * path against the base URI , a leading '/' in a path is 
036     * ignored and base URIs are treated as if they ended in '/'. E.g.:</p>
037     * 
038     * <pre>&#64;Path("widgets")
039     *public class WidgetsResource {
040     *  &#64;GET
041     *  String getList() {...}
042     * 
043     *  &#64;GET &#64;Path("{id}")
044     *  String getWidget(&#64;PathParam("id") String id) {...}
045     *}</pre>
046     * 
047     * <p>In the above, if the application path is
048     * <code>catalogue</code> and the application is deployed at
049     * <code>http://example.com/</code>, then <code>GET</code> requests for
050     * <code>http://example.com/catalogue/widgets</code> will be handled by the
051     * <code>getList</code> method while requests for
052     * <code>http://example.com/catalogue/widgets/<i>nnn</i></code> (where 
053     * <code><i>nnn</i></code> is some value) will be handled by the
054     * <code>getWidget</code> method. The same would apply if the value of either
055     * <code>&#64;Path</code> annotation started with '/'.
056     * 
057     * <p>Classes and methods may also be annotated with {@link Consumes} and 
058     * {@link Produces} to filter the requests they will receive.</p>
059     * 
060     * @see Consumes
061     * @see Produces
062     * @see PathParam
063     */
064    @Target({ElementType.TYPE, ElementType.METHOD})
065    @Retention(RetentionPolicy.RUNTIME)
066    public @interface Path {
067        /**
068         * Defines a URI template for the resource class or method, must not 
069         * include matrix parameters.
070         * 
071         * <p>Embedded template parameters are allowed and are of the form:</p>
072         * 
073         * <pre> param = "{" *WSP name *WSP [ ":" *WSP regex *WSP ] "}"
074         * name = (ALPHA / DIGIT / "_")*(ALPHA / DIGIT / "." / "_" / "-" ) ; \w[\w\.-]*
075         * regex = *( nonbrace / "{" *nonbrace "}" ) ; where nonbrace is any char other than "{" and "}"</pre>
076         * 
077         * <p>See {@link <a href="http://tools.ietf.org/html/rfc5234">RFC 5234</a>} 
078         * for a description of the syntax used above and the expansions of 
079         * {@code WSP}, {@code ALPHA} and {@code DIGIT}. In the above {@code name}
080         * is the template parameter name and the optional {@code regex} specifies 
081         * the contents of the capturing group for the parameter. If {@code regex}
082         * is not supplied then a default value of {@code [^/]+} which terminates at
083         * a path segment boundary, is used. Matching of request URIs to URI 
084         * templates is performed against encoded path values and implementations
085         * will not escape literal characters in regex automatically, therefore any
086         * literals in {@code regex} should be escaped by the author according to
087         * the rules of
088         * {@link <a href="http://tools.ietf.org/html/rfc3986#section-3.3">RFC 3986 section 3.3</a>}.
089         * Caution is recommended in the use of {@code regex}, incorrect use can
090         * lead to a template parameter matching unexpected URI paths. See 
091         * {@link <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">Pattern</a>}
092         * for further information on the syntax of regular expressions.
093         * Values of template parameters may be extracted using {@link PathParam}.
094         *
095         * <p>The literal part of the supplied value (those characters
096         * that are not part of a template parameter) is automatically percent 
097         * encoded to conform to the {@code path} production of 
098         * {@link <a href="http://tools.ietf.org/html/rfc3986#section-3.3">RFC 3986 section 3.3</a>}.
099         * Note that percent encoded values are allowed in the literal part of the
100         * value, an implementation will recognize such values and will not double
101         * encode the '%' character.</p>
102         */
103        String value();
104        
105    }