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.io.*;
019import java.lang.annotation.*;
020
021/**
022 * REST response body annotation.
023 *
024 * <p>
025 * Annotation used to denote an HTTP response body.
026 *
027 * <p>
028 * Can be used in the following locations:
029 * <ul>
030 *    <li>Methods and return types of server-side and client-side <ja>@Response</ja>-annotated interfaces.
031 * </ul>
032 *
033 *
034 * <h5 class='topic'>Public methods of <ja>@Response</ja>-annotated methods</h5>
035 * <p>
036 * On {@link Response @Response}-annotated classes, this method can be used to denote a POJO to use as the response.
037 *
038 * <p>
039 * The method must be public and be one of the following:
040 * <ul>
041 *    <li>A public no-arg method with a POJO return type.
042 *    <li>A public one-arg method with a <jk>void</jk> return type that takes in a {@link Reader} or {@link OutputStream}.
043 * </ul>
044 *
045 * <h5 class='section'>Example:</h5>
046 * <p class='bcode w800'>
047 *    <ja>@RestMethod</ja>
048 *    <jk>public</jk> AddPetSuccess addPet() {
049 *       <jsm>addPet</jsm>(pet);
050 *       <jk>return new</jk> AddPetSuccess(...);
051 *    }
052 * </p>
053 *
054 * <h5 class='figure'>Example:</h5>
055 * <p class='bcode w800'>
056 *    <ja>@Response</ja>
057 *    <jk>public class</jk> AddPetSuccess {
058 *
059 *       <ja>@ResponseBody</ja>
060 *       <jk>public</jk> Pet getPet() {...}
061 *    }
062 * </p>
063 *
064 * <h5 class='section'>Example:</h5>
065 * <p class='bcode w800'>
066 *    <ja>@Response</ja>
067 *    <jk>public class</jk> MyCustomJsonResponse {
068 *
069 *       <ja>@ResponseHeader</ja>(<js>"Content-Type"</js>)
070 *       <jk>public</jk> String getContentType() {
071 *          <jk>return</jk> <js>"application/json"</js>;
072 *       }
073 *
074 *       <ja>@ResponseBody</ja>
075 *       <jk>public void</jk> writeTo(Writer out) {
076 *          out.write(<js>"{'foo':'bar'}"</js>);
077 *       }
078 *    }
079 * </p>
080 *
081 * <h5 class='topic'>Methods and return types of server-side and client-side @Response-annotated interfaces</h5>
082 *
083 * <ul class='seealso'>
084 *    <li class='link'>{@doc RestResponseAnnotation}
085 *    <li class='link'>{@doc RestcResponse}
086 * </ul>
087 */
088@Documented
089@Target(METHOD)
090@Retention(RUNTIME)
091@Inherited
092public @interface ResponseBody {}