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