1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2016 ForgeRock AS.
15 */
16
17 package org.forgerock.api.annotations;
18
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23
24 /**
25 * Allocate a path to a component.
26 * <p>
27 * This annotation can be applied to either a method or a type:
28 * <ul>
29 * <li>
30 * Method - the method should return a handleable type - i.e. either a {@code RequestHandler}, an annotated
31 * POJO, or an implementation of a resource handler interface. This will expose the returned object as a subpath
32 * beneath the handler that the method is a member of.
33 * </li>
34 * <li>
35 * Type - declare the path of a handleable type, so that the path does not have to be declared in a separate
36 * interaction with a router. Note that if the {@code @Path}-annotated handleable type is returned from a method
37 * on another type also annotated with {@code @Path}, then the type annotation is ignored.
38 * </li>
39 * </ul>
40 * <p>
41 * Example:
42 * <code><pre>
43 * @RequestHandler(variant = COLLECTION_RESOURCE)
44 * @Path("things")
45 * public class ThingProducer {
46 * @Read
47 * public Promise<ResourceResponse, ResourceException> get(String id) {
48 * // ...
49 * }
50 *
51 * @Path("{thing}/subthing")
52 * public SubthingProducer subthing() {
53 * return new SubthingProducer();
54 * }
55 * }
56 *
57 * @RequestHandler(variant = SINGLETON_RESOURCE)
58 * public class SubthingProducer {
59 * @Read
60 * public Promise<ResourceResponse, ResourceException> get() {
61 * // ...
62 * }
63 * }
64 * </pre></code>
65 * In this example, when an instance of {@code ThingProducer} would result in the following paths being created:
66 * <ul>
67 * <li>{@code /things} - collection binding to {@code ThingProducer}</li>
68 * <li>{@code /things/{id}} - instance binding to {@code ThingProducer}</li>
69 * <li>{@code /things/{thing}/subthing} - singleton binding to {@code SubthingProducer}</li>
70 * </ul>
71 */
72 @Retention(RetentionPolicy.RUNTIME)
73 @Target({ ElementType.METHOD, ElementType.TYPE })
74 public @interface Path {
75 /** The path value. */
76 String value();
77 }