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
024import org.apache.juneau.commons.*;
025
026/**
027 * REST request header annotation.
028 *
029 * <p>
030 * Identifies a POJO to be used as the header of an HTTP request.
031 *
032 * <p>
033 * Can be used in the following locations:
034 * <ul>
035 *    <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods.
036 *    <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces.
037 *    <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces.
038 * </ul>
039 *
040 * <h2 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h2>
041 * <p>
042 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as a HTTP
043 * request header.
044 *
045 * <h2 class='section'>Example:</h2>
046 * <p class='bjava'>
047 *    <ja>@RestGet</ja>
048 *    <jk>public void</jk> doGet(<ja>@Header</ja>(<js>"ETag"</js>) UUID <jv>etag</jv>) {...}
049 * </p>
050 *
051 * <p>
052 * This is functionally equivalent to the following code...
053 * <p class='bjava'>
054 *    <ja>@RestGet</ja>
055 *    <jk>public void</jk> doGet(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
056 *       UUID <jv>etag</jv> = <jv>req</jv>.getHeader(<js>"ETag"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
057 *       ...
058 *    }
059 * </p>
060 *
061 * <h2 class='section'>See Also:</h2><ul>
062 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
063 *    <li class='extlink'><a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>
064 * </ul>
065 *
066 * <h2 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h2>
067 * <p>
068 * Annotation applied to Java method arguments of interface proxies to denote that they are serialized as an HTTP
069 * header value.
070 *
071 * <h2 class='section'>See Also:</h2><ul>
072 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Header">@Header</a>
073 * </ul>
074 *
075 * <h2 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h2>
076 * <h2 class='section'>See Also:</h2><ul>
077 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a>
078 * </ul>
079 */
080@Documented
081@Target({ PARAMETER, METHOD, TYPE, FIELD })
082@Retention(RUNTIME)
083@Inherited
084public @interface Header {
085
086   /**
087    * Default value for this parameter.
088    *
089    * @return The annotation value.
090    */
091   String def() default "";
092
093   /**
094    * Optional description for the exposed API.
095    *
096    * @return The annotation value.
097    * @since 9.2.0
098    */
099   String[] description() default {};
100
101   /**
102    * Short, concise summary of the exposed API.
103    *
104    * <p>
105    * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation,
106    * or any context where brevity matters. See {@link Schema#summary()}
107    * for the canonical definition.
108    *
109    * @return The annotation value.
110    * @since 10.0.0
111    */
112   String summary() default "";
113
114   /**
115    * HTTP header name.
116    * <p>
117    * A blank value (the default) indicates to reuse the bean property name when used on a request bean property.
118    *
119    * <p>
120    * The value should be either a valid HTTP header name, or <js>"*"</js> to represent multiple name/value pairs
121    *
122    * <p>
123    * A blank value (the default) has the following behavior:
124    * <ul class='spaced-list'>
125    *    <li>
126    *       If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean,
127    *       then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs.
128    *
129    *       <h4 class='figure'>Examples:</h4>
130    *       <p class='bjava'>
131    *    <jc>// When used on a REST method</jc>
132    *    <ja>@RestPost</ja>(<js>"/addPet"</js>)
133    *    <jk>public void</jk> addPet(<ja>@Header</ja> JsonMap <jv>allHeaderParameters</jv>) {...}
134    *       </p>
135    *       <p class='bjava'>
136    *    <jc>// When used on a remote method parameter</jc>
137    *    <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>)
138    *    <jk>public interface</jk> MyProxy {
139    *
140    *       <jc>// Equivalent to @Header("*")</jc>
141    *       <ja>@RemoteGet</ja>(<js>"/mymethod"</js>)
142    *       String myProxyMethod1(<ja>@Header</ja> Map&lt;String,Object&gt; <jv>allHeaderParameters</jv>);
143    *    }
144    *       </p>
145    *       <p class='bjava'>
146    *    <jc>// When used on a request bean method</jc>
147    *    <jk>public interface</jk> MyRequest {
148    *
149    *       <jc>// Equivalent to @Header("*")</jc>
150    *       <ja>@Header</ja>
151    *       Map&lt;String,Object&gt; getFoo();
152    *    }
153    *       </p>
154    *    </li>
155    *    <li>
156    *       If used on a request bean method, uses the bean property name.
157    *
158    *       <h4 class='figure'>Example:</h4>
159    *       <p class='bjava'>
160    *    <jk>public interface</jk> MyRequest {
161    *
162    *       <jc>// Equivalent to @Header("Foo")</jc>
163    *       <ja>@Header</ja>
164    *       <ja>@BeanProp</ja>(<js>"Foo"</js>)
165    *       String getFoo();
166    *    }
167    *       </p>
168    *    </li>
169    * </ul>
170    *
171    * @return The annotation value.
172    */
173   String name() default "";
174
175   /**
176    * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>.
177    *
178    * <p>
179    * The schema defining the type used for parameter.
180    *
181    * <p>
182    * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type.
183    * Values specified on this field override values specified on the type, and values specified on child types override values
184    * specified on parent types.
185    *
186    * <h4 class='section'>Used for:</h4>
187    * <ul class='spaced-list'>
188    *    <li>
189    *       Server-side schema-based parsing and parsing validation.
190    *    <li>
191    *       Server-side generated Swagger documentation.
192    *    <li>
193    *       Client-side schema-based serializing and serializing validation.
194    * </ul>
195    *
196    * @return The annotation value.
197    */
198   Schema schema() default @Schema;
199
200   /**
201    * A synonym for {@link #name()}.
202    *
203    * <p>
204    * Allows you to use shortened notation if you're only specifying the name.
205    *
206    * <p>
207    * The following are completely equivalent ways of defining a header entry:
208    * <p class='bjava'>
209    *    <jk>public</jk> Order placeOrder(<ja>@Header</ja>(name=<js>"api_key"</js>) String <jv>apiKey</jv>) {...}
210    * </p>
211    * <p class='bjava'>
212    *    <jk>public</jk> Order placeOrder(<ja>@Header</ja>(<js>"api_key"</js>) String <jv>apiKey</jv>) {...}
213    * </p>
214    *
215    * @return The annotation value.
216    */
217   String value() default "";
218}