001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2016 ForgeRock AS.
015 */
016
017package org.forgerock.api.annotations;
018
019import java.lang.annotation.ElementType;
020import java.lang.annotation.Retention;
021import java.lang.annotation.RetentionPolicy;
022import java.lang.annotation.Target;
023
024/**
025 * Allocate a path to a component.
026 * <p>
027 * This annotation can be applied to either a method or a type:
028 * <ul>
029 *     <li>
030 *         Method - the method should return a handleable type - i.e. either a {@code RequestHandler}, an annotated
031 *         POJO, or an implementation of a resource handler interface. This will expose the returned object as a subpath
032 *         beneath the handler that the method is a member of.
033 *     </li>
034 *     <li>
035 *         Type - declare the path of a handleable type, so that the path does not have to be declared in a separate
036 *         interaction with a router. Note that if the {@code @Path}-annotated handleable type is returned from a method
037 *         on another type also annotated with {@code @Path}, then the type annotation is ignored.
038 *     </li>
039 * </ul>
040 * <p>
041 * Example:
042 * <code><pre>
043 *     &#064;RequestHandler(variant = COLLECTION_RESOURCE)
044 *     &#064;Path("things")
045 *     public class ThingProducer {
046 *         &#064;Read
047 *         public Promise&lt;ResourceResponse, ResourceException&gt; get(String id) {
048 *             // ...
049 *         }
050 *
051 *         &#064;Path("{thing}/subthing")
052 *         public SubthingProducer subthing() {
053 *             return new SubthingProducer();
054 *         }
055 *     }
056 *
057 *     &#064;RequestHandler(variant = SINGLETON_RESOURCE)
058 *     public class SubthingProducer {
059 *         &#064;Read
060 *         public Promise&lt;ResourceResponse, ResourceException&gt; get() {
061 *             // ...
062 *         }
063 *     }
064 * </pre></code>
065 * In this example, when an instance of {@code ThingProducer} would result in the following paths being created:
066 * <ul>
067 *     <li>{@code /things} - collection binding to {@code ThingProducer}</li>
068 *     <li>{@code /things/{id}} - instance binding to {@code ThingProducer}</li>
069 *     <li>{@code /things/{thing}/subthing} - singleton binding to {@code SubthingProducer}</li>
070 * </ul>
071 */
072@Retention(RetentionPolicy.RUNTIME)
073@Target({ ElementType.METHOD, ElementType.TYPE })
074public @interface Path {
075    /** The path value. */
076    String value();
077}