All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.ws.rs.Path Maven / Gradle / Ivy

/*
 * 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(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy