/*
 * Copyright (C) 2014 Civilian Framework.
 *
 * Licensed under the Civilian License (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.civilian-framework.org/license.txt
 *
 * 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.
 */
package org.civilian.annotation;


import java.lang.annotation.Documented;
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;


/**
 * Path is an annotation to define a resource mapping.
 * It can be used on
 * <ol>
 * <li><a href="#p">packages</a> containing controller classes
 * <li><a href="#c">controller classes</a>
 * <li><a href="#m">controller action methods</a>
 * </ol>
 * It allows to override the mapping of a package or controller class
 * to a resource, or to introduce a mapping of a controller method
 * to a resource.
 * You can annotate a package in package-info.java placed in the package
 * directory.
 * The {@link #value() value} of the annotation is a relative path string.
 * It is interpreted as follows:
 * <a name="p"></a>
 * <h1>Used on controller packages</h1>
 * The path string overrides the default mapping of the controller
 * package to a resource, relative to its parent package.
 * The path string must not be empty.<br>
 * Example:<br>
 * Suppose the parent controller package "com.app.contacts" is mapped to resource "/contacts".
 * Package "com.app.contacts.detail" would by default be mapped to 
 * resource "/contacts/detail".<br>
 * But annotated with @Path("showdetails") it would be mapped to resource 
 * "/contacts/showdetails".
 * <a name="c"></a>
 * <h1>Used on controller classes</h1>
 * The path string overrides the default mapping of the controller
 * class to a resource, relative to its package.
 * The path string may be empty.
 * Example:<br>
 * Suppose the controller package "com.app.contacts" is mapped to resource "/contacts".
 * The controller class "com.app.contacts.ViewController" would by default be mapped to 
 * resource "/contacts/view".<br>
 * But annotated with @Path("show") it would be mapped to resource 
 * "/contacts/show". If annotated with @Path("") it would be mapped to resource 
 * "/contacts".
 * <a name="m"></a>
 * <h1>Used on controller action methods</h1>
 */
@Target({ElementType.PACKAGE, ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
public @interface Path
{
	/**
	 * Returns the path value.
	 */
	public String value();
}