001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * REST response status annotation.
026 *
027 * <p>
028 * Annotation used to denote an HTTP response status code.
029 *
030 * <p>
031 * Can be used in the following locations:
032 * <ul>
033 *    <li>Arguments of server-side <ja>@RestOp</ja>-annotated methods.
034 *    <li>Methods and return types of server-side and client-side <ja>@Response</ja>-annotated interfaces.
035 * </ul>
036 *
037 * <h5 class='topic'>Arguments of server-side <ja>@RestOp</ja>-annotated methods</h5>
038 *
039 * <p>
040 * On server-side REST, this annotation can be applied to method parameters to identify them as an HTTP response value.
041 *
042 * <h5 class='section'>Example:</h5>
043 * <p class='bjava'>
044 *    <ja>@RestPost</ja>
045 *    <jk>public void</jk> addPet(<ja>@Content</ja> Pet <jv>pet</jv>, <ja>@StatusCode</ja> Holder&lt;Integer&gt; <jv>status</jv>) {
046 *       <jsm>addPet</jsm>(<jv>pet</jv>);
047 *       <jv>status</jv>.set(200);
048 *    }
049 * </p>
050 *
051 * <p>
052 * The parameter type must be {@link org.apache.juneau.commons.inject.Value} with a parameterized type of {@link Integer}.
053 *
054 * <h5 class='topic'>Public methods of <ja>@Response</ja>-annotated types</h5>
055 *
056 * <p>
057 * On {@link Response @Response}-annotated classes, this method can be used to denote an HTTP status code on a response.
058 *
059 * <h5 class='section'>Example:</h5>
060 * <p class='bjava'>
061 *    <ja>@RestPost</ja>
062 *    <jk>public</jk> Success addPet(Pet <jv>pet</jv>) {
063 *       <jsm>addPet</jsm>(<jv>pet</jv>);
064 *       <jk>return new</jk> Success();
065 *    }
066 * </p>
067 *
068 * <p class='bjava'>
069 *    <ja>@Response</ja>
070 *    <jk>public class</jk> Success {
071 *
072 *       <ja>@StatusCode</ja>
073 *       <jk>public int</jk> getStatus() {
074 *          <jk>return</jk> 201;
075 *       }
076 *
077 *       <ja>@Override</ja>
078 *       <jk>public</jk> String toString() {
079 *          <jk>return</jk> <js>"Pet was successfully added"</js>;
080 *       }
081 *    }
082 * </p>
083 *
084 * <p>
085 * The method being annotated must be public and return a numeric value.
086 *
087 *
088 * <h5 class='section'>See Also:</h5><ul>
089 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
090 * </ul>
091 *
092 * <h5 class='topic'>Methods and return types of server-side and client-side @Response-annotated interfaces</h5>
093 *
094 * <h5 class='section'>See Also:</h5><ul>
095 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Response">@Response</a>
096 * </ul>
097 *
098 * <p>
099 */
100@Documented
101@Target({ PARAMETER, METHOD, TYPE })
102@Retention(RUNTIME)
103@Inherited
104public @interface StatusCode {
105
106   /**
107    * Optional description for the exposed API.
108    *
109    * @return The annotation value.
110    * @since 9.2.0
111    */
112   String[] description() default {};
113
114   /**
115    * The HTTP response codes.
116    *
117    * The default value is <c>500</c> for exceptions and <c>200</c> for return types.
118    *
119    * @return The annotation value.
120    */
121   int[] value() default {};
122}