org.apache.juneau.http.annotation.ResponseHeader Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * 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. *
// ***************************************************************************************************************************
package org.apache.juneau.http.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.*;
import org.apache.juneau.httppart.*;
import org.apache.juneau.oapi.*;
/**
* REST response header annotation.
*
*
* Annotation used to denote an HTTP response header.
*
*
* Can be used in the following locations:
*
* - Arguments of server-side
@RestMethod -annotated methods.
* - Methods and return types of server-side and client-side
@Response -annotated interfaces.
*
*
* Arguments of server-side @RestMethod -annotated methods
*
*
* On server-side REST, this annotation can be applied to method parameters to identify them as an HTTP response header.
*
In this case, the annotation can only be applied to subclasses of type {@link Value}.
*
*
* The following examples show 3 different ways of accomplishing the same task of setting an HTTP header
* on a response:
*
*
* // Example #1 - Setting header directly on RestResponse object.
* @RestMethod (...)
* public void login(RestResponse res) {
* res.setHeader("X-Rate-Limit" , 1000);
* ...
* }
*
* // Example #2 - Use on parameter.
* @RestMethod (...)
* public void login(
* @ResponseHeader (
* name="X-Rate-Limit" ,
* type="integer" ,
* format="int32" ,
* description="Calls per hour allowed by the user." ,
* example="123"
* )
* Value<Integer> rateLimit
* ) {
* rateLimit.set(1000);
* ...
* }
*
* // Example #3 - Use on type.
* @RestMethod (...)
* public void login(Value<RateLimit> rateLimit) {
* rateLimit.set(new RateLimit(1000));
* ...
* }
*
* @ResponseHeader (
* name="X-Rate-Limit" ,
* type="integer" ,
* format="int32" ,
* description="Calls per hour allowed by the user." ,
* example="123"
* )
* public class RateLimit {
* // OpenApiPartSerializer knows to look for this method based on format/type.
* public Integer toInteger() {
* return 1000;
* }
* }
*
*
* Public methods of @Response-annotated types
*
*
* On server-side REST, this annotation can also be applied to public methods of {@link Response}-annotated methods.
*
*
* @Response
* public class AddPetSuccess {
*
* @ResponseHeader (
* name="X-PetId" ,
* type="integer" ,
* format="int32" ,
* description="ID of added pet." ,
* example="123"
* )
* public int getPetId() {...}
* }
*
*
*
* See Also:
*
* - {@doc juneau-rest-server.HttpPartAnnotations.ResponseHeader}
*
- {@doc juneau-rest-server.Swagger}
*
- {@doc SwaggerHeaderObject}
*
*
* Methods and return types of server-side and client-side @Response-annotated interfaces
*
* See Also:
*
* - {@doc juneau-rest-server.HttpPartAnnotations.Response}
*
- {@doc juneau-rest-client.RestProxies.Response}
*
*/
@Documented
@Target({PARAMETER,METHOD,TYPE})
@Retention(RUNTIME)
@Inherited
public @interface ResponseHeader {
/**
* The HTTP status (or statuses) of the response.
*
* Notes:
*
* -
* The is a comma-delimited list of HTTP status codes that this header applies to.
*
-
* The default value is
"200" .
*
*/
int[] code() default {};
/**
* The HTTP header name.
*
* Notes:
*
* -
* The format is plain-text.
*
*/
String name() default "";
/**
* A synonym for {@link #name()}.
*
*
* Allows you to use shortened notation if you're only specifying the name.
*
*
* The following are completely equivalent ways of defining a response header:
*
* @ResponseHeader (name="X-Rate-Limit" ) Value<Integer> rateLimit)
*
*
* @ResponseHeader ("X-Rate-Limit" ) Value<Integer> rateLimit)
*
*/
String value() default "";
/**
* Specifies the {@link HttpPartSerializer} class used for serializing values to strings.
*
*
* Overrides for this part the part serializer defined on the REST resource which by default is {@link OpenApiSerializer}.
*/
Class serializer() default HttpPartSerializer.Null.class;
/**
* description field of the {@doc SwaggerHeaderObject}.
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*
* Notes:
*
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] description() default {};
/**
* type field of the {@doc SwaggerHeaderObject}.
*
*
* The type of the parameter.
*
*
* The possible values are:
*
* -
*
"string"
* -
*
"number"
* -
*
"integer"
* -
*
"boolean"
* -
*
"array"
* -
*
"object"
* -
*
"file"
*
*
*
* Static strings are defined in {@link ParameterType}.
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*
* See Also:
*
* - {@doc SwaggerDataTypes}
*
*/
String type() default "";
/**
* format field of the {@doc SwaggerHeaderObject}.
*
*
* The possible values are:
*
* -
*
"int32" - Signed 32 bits.
*
Only valid with type "integer" .
* -
*
"int64" - Signed 64 bits.
*
Only valid with type "integer" .
* -
*
"float" - 32-bit floating point number.
*
Only valid with type "number" .
* -
*
"double" - 64-bit floating point number.
*
Only valid with type "number" .
* -
*
"byte" - BASE-64 encoded characters.
*
Only valid with type "string" .
* -
*
"binary" - Hexadecimal encoded octets (e.g. "00FF" ).
*
Only valid with type "string" .
* -
*
"date" - An RFC3339 full-date.
*
Only valid with type "string" .
* -
*
"date-time" - An RFC3339 date-time.
*
Only valid with type "string" .
* -
*
"password" - Used to hint UIs the input needs to be obscured.
* -
*
"uon" - UON notation (e.g. "(foo=bar,baz=@(qux,123))" ).
*
Only valid with type "object" .
*
*
*
* Static strings are defined in {@link FormatType}.
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*
* See Also:
*
* - {@doc SwaggerDataTypeFormats}
*
*/
String format() default "";
/**
* collectionFormat field of the {@doc SwaggerHeaderObject}.
*
*
* Determines the format of the array if type "array" is used.
*
Can only be used if type is "array" .
*
*
Possible values are:
*
* -
*
"csv" (default) - Comma-separated values (e.g. "foo,bar" ).
* -
*
"ssv" - Space-separated values (e.g. "foo bar" ).
* -
*
"tsv" - Tab-separated values (e.g. "foo\tbar" ).
* -
*
"pipes - Pipe-separated values (e.g. "foo|bar" ).
* -
*
"multi" - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. "foo=bar&foo=baz" ).
* -
*
"uon" - UON notation (e.g. "@(foo,bar)" ).
*
*
*
* Static strings are defined in {@link CollectionFormatType}.
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*
*
* Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
*/
String collectionFormat() default "";
/**
* $ref field of the {@doc SwaggerHeaderObject}.
*
*
* Denotes a reference to a definition object.
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String $ref() default "";
/**
* maximum field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String maximum() default "";
/**
* minimum field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String minimum() default "";
/**
* multipleOf field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String multipleOf() default "";
/**
* maxLength field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
long maxLength() default -1;
/**
* minLength field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
long minLength() default -1;
/**
* pattern field of the {@doc SwaggerHeaderObject}.
*
*
* A string value is valid if it matches the specified regular expression pattern.
*
*
* If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
*
*
* Only allowed for the following types: "string" .
*
*
Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String pattern() default "";
/**
* maxItems field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
long maxItems() default -1;
/**
* minItems field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
long minItems() default -1;
/**
* exclusiveMaximum field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
boolean exclusiveMaximum() default false;
/**
* exclusiveMinimum field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
boolean exclusiveMinimum() default false;
/**
* uniqueItems field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
boolean uniqueItems() default false;
/**
* items field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
Items items() default @Items;
/**
* default field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String[] _default() default {};
/**
* enum field of the {@doc SwaggerHeaderObject}.
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String[] _enum() default {};
/**
* A serialized example of the parameter.
*
*
* This attribute defines a representation of the value that is used by BasicRestInfoProvider to construct
* an example of parameter.
*
*
Example:
*
* @ResponseHeader (
* name="Status" ,
* type="array" ,
* collectionFormat="csv" ,
* example="AVALIABLE,PENDING"
* )
*
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*/
String[] example() default {};
/**
* Free-form value for the {@doc SwaggerHeaderObject}.
*
*
* This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this field.
*
*
* The following are completely equivalent ways of defining the swagger description of the Header object:
*
* // Normal
* @ResponseHeader (
* name="Location" ,
* description="The new location of this resource" ,
* type="string" ,
* format="uri"
* )
*
*
* // Free-form
* @ResponseHeader (
* name="Location" ,
* api={
* "description: 'The new location of this resource'," ,
* "type: 'string'," ,
* "format: 'uri'"
* }
* )
*
*
* // Free-form using variables
* @ResponseHeader (
* name="Location" ,
* api="$L{locationSwagger}"
* )
*
*
* // Contents of MyResource.properties
* locationSwagger = { description: "The new location of this resource", type: "string", format: "uri" }
*
*
*
* The reasons why you may want to use this field include:
*
* - You want to pull in the entire Swagger JSON definition for this body from an external source such as a properties file.
*
- You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
*
*
* Used for:
*
* -
* Server-side generated Swagger documentation.
*
*
* Notes:
*
* -
* Note that the only swagger field you can't specify using this value is
"name" whose value needs to be known during servlet initialization.
* -
* The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
-
* The leading/trailing
{ } characters are optional.
*
The following two example are considered equivalent:
*
* @ResponseHeader ("{description:'The new location of this resource'}" )
*
*
* @ResponseHeader ("description:'The new location of this resource'" )
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
*
*/
String[] api() default {};
}