<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

@ResponseHeader

<p>
	The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be applied to <ja>@RestMethod</ja>-annotated parameters to denote them as an HTTP response headers.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.annotation.ResponseHeader}
	<ul>
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#_default() _default} - Default value if not present.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#_enum() _enum} - Output validation.  Must match one of the values.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#$ref() $ref} - Schema reference.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#api() api} - Free-form Swagger JSON.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#code() code} - HTTP status codes that this header applies to.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#collectionFormat() collectionFormat} - How collections of items are formatted.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#description() description} - Description.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#example() example} - Serialized example.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#exclusiveMaximum() exclusiveMaximum} - Output validation.  Whether maximum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#exclusiveMinimum() exclusiveMinimum} - Output validation.  Whether minimum is exclusive.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#format() format} - The schema type format.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#items() items} - The schema of items in a collection.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#maximum() maximum} - Output validation.  Maximum numeric value. 
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#maxItems() maxItems} - Output validation.  Maximum number of items in a collection. 
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#maxLength() maxLength} - Output validation.  Maximum length of a string.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#minimum() minimum} - Output validation.  Minimum numeric value. 
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#minItems() minItems} - Output validation.  Minimum number of items in a collection. 
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#minLength() minLength} - Output validation.  Minimum length of a string.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#multipleOf() multipleOf} - Output validation.  Number must be a multiple of.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#name() name} - Header name.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#pattern() pattern} - Output validation.  Must match regular expression.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#serializer() serializer} - Override the part serializer.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#type() type} - The schema type.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#uniqueItems() uniqueItems} - Output validation. Collections must contain unique items only.
		<li class='jf'>{@link oaj.http.annotation.ResponseHeader#value() value} - Free-form Swagger JSON.
	</ul>
</ul>
<p>
	This annotation can only be applied to parameters of type {@link oaj.Value}.
</p>
<p>
	The following examples show 3 different ways of accomplishing the same task of setting an HTTP header
	on a response:
</p>
<p class='bpcode w800'>
	<jc>// Example #1 - Setting header directly on RestResponse object.</jc>
	<ja>@RestMethod</ja>(...)
	<jk>public void</jk> login(RestResponse res) {
		res.setHeader(<js>"X-Rate-Limit"</js>, 1000);
		...
	}
 
	<jc>// Example #2 - Use on parameter.</jc>
	<ja>@RestMethod</ja>(...)
	<jk>public void</jk> login(
			<ja>@ResponseHeader</ja>(
				name=<js>"X-Rate-Limit"</js>,
				type=<js>"integer"</js>,
				format=<js>"int32"</js>,
				description=<js>"Calls per hour allowed by the user."</js>,
				example=<js>"123"</js>
			)
			Value&lt;Integer&gt; rateLimit
 	) 
 	{
		rateLimit.set(1000);
		...
	}

	<jc>// Example #3 - Use on type.</jc>
	<ja>@RestMethod</ja>(...)
	<jk>public void</jk> login(Value&lt;RateLimit&gt; rateLimit) {
		rateLimit.set(<jk>new</jk> RateLimit());
		...
	}

	<ja>@ResponseHeader</ja>(
		name=<js>"X-Rate-Limit"</js>, 
		type=<js>"integer"</js>, 
		format=<js>"int32"</js>, 
		description=<js>"Calls per hour allowed by the user."</js>, 
		example=<js>"123"</js>
	)
	<jk>public class</jk> RateLimit {
		<jc>// OpenApiSerializer knows to look for this method based on format/type.</jc>
		<jk>public</jk> Integer toInteger() {
			<jk>return</jk> 1000;
		}
	}
</p>

<h5 class='topic'>Swagger documentation</h5>
<p>
	The attributes on this annotation are also used to populate the generated Swagger for the method.
	For example, in the case of the <c>X-Rate-Limit</c> example above, the following Swagger is generated:
</p>
<p class='bpcode w800'>
	<jok>'/user/login'</jok>: {
		<jok>get</jok>: {
			<jok>responses</jok>: {
				<jok>200</jok>: {
					<jok>headers</jok>: {
						<jok>'X-Rate-Limit'</jok>: {
							<jok>type</jok>: <jov>'integer'</jov>,
							<jok>format</jok>: <jov>'int32'</jov>,
							<jok>description</jok>: <jov>'Calls per hour allowed by the user.'</jov>,
							<jok>example</jok>: <jov>'123'</jov>
						}
					}
				}
			}
		}
	}
</p>