1 package com.atlassian.rest.annotation;
2
3 import java.lang.annotation.ElementType;
4 import java.lang.annotation.Retention;
5 import java.lang.annotation.RetentionPolicy;
6 import java.lang.annotation.Target;
7
8 /**
9 * Declares an actual type returned by a REST method so that the WADL generator can create JSON schemas.
10 *
11 * <p>
12 * This annotation can be placed on a single method and also on a class. When it's on
13 * a class that means it's applied to all methods in this class. That's useful for declaring
14 * error types, as they are usually the same for all methods.
15 * </p>
16 *
17 * <p>
18 * Use {@link ResponseTypes} annotation to declare more than one return type.
19 * </p>
20 *
21 */
22 @Retention (RetentionPolicy.RUNTIME)
23 @Target ({ElementType.METHOD, ElementType.TYPE})
24 public @interface ResponseType
25 {
26 enum StatusType
27 {
28 /**
29 * All success (2xx) status codes
30 */
31 SUCCESS("2\\d\\d"),
32 /**
33 * All redirect (3xx) status codes
34 */
35 REDIRECTION("3\\d\\d"),
36 /**
37 * All client error (4xx) status codes
38 */
39 CLIENT_ERROR("4\\d\\d"),
40 /**
41 * All server error (5xx) status codes
42 */
43 SERVER_ERROR("5\\d\\d");
44
45 private final String pattern;
46
47 StatusType(String pattern)
48 {
49 this.pattern = pattern;
50 }
51
52 public boolean matches(int status)
53 {
54 return String.valueOf(status).matches(pattern);
55 }
56 }
57
58 /**
59 * Status for which this type applies. Note that for the JSON schema
60 * generation to work, the type also needs to be declared in the javadoc.
61 *
62 * @return status
63 */
64 int status() default 0;
65
66 /**
67 * General type of the status.
68 *
69 * <p>
70 * Instead of specifying an exact status, you can select a group of statues.
71 * If any status from the group is present in the method's javadoc, it will
72 * have a schema generated for the type declared here.
73 * </p>
74 *
75 * @return
76 */
77 StatusType statusType() default StatusType.SUCCESS;
78
79 /**
80 * Type of the returned response.
81 */
82 Class<?> value();
83
84 /**
85 * If the response class is generic you are supposed to provide all its generic types here.
86 */
87 Class<?>[] genericTypes() default {};
88 }