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.rest.annotation;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.io.*;
023import java.lang.annotation.*;
024import java.util.*;
025import java.util.logging.*;
026
027import org.apache.juneau.*;
028import org.apache.juneau.config.*;
029import org.apache.juneau.cp.*;
030import org.apache.juneau.http.header.*;
031import org.apache.juneau.rest.*;
032import org.apache.juneau.rest.converter.*;
033import org.apache.juneau.rest.httppart.*;
034
035import jakarta.servlet.*;
036import jakarta.servlet.http.*;
037
038/**
039 * Identifies a method that gets called immediately after the <ja>@RestOp</ja> annotated method gets called.
040 *
041 * <p>
042 * At this point, the output object returned by the method call has been set on the response, but
043 * {@link RestConverter RestConverters} have not yet been executed and the response has not yet been written.
044 *
045 * <p>
046 * The list of valid parameter types are as follows:
047 * <ul>
048 *    <li>Servlet request/response objects:
049 *       <ul class='javatreec'>
050 *          <li>{@link HttpServletRequest}
051 *          <li>{@link HttpServletResponse}
052 *       </ul>
053 *    <li>Extended request/response objects:
054 *       <ul class='javatreec'>
055 *          <li>{@link RestRequest}
056 *          <li>{@link RestResponse}
057 *       </ul>
058 *    <li>Header objects:
059 *       <ul class='javatreec'>
060 *          <li>{@link Accept}
061 *          <li>{@link AcceptCharset}
062 *          <li>{@link AcceptEncoding}
063 *          <li>{@link AcceptLanguage}
064 *          <li>{@link Authorization}
065 *          <li>{@link CacheControl}
066 *          <li>{@link Connection}
067 *          <li>{@link ContentLength}
068 *          <li>{@link ContentType}
069 *          <li>{@link org.apache.juneau.http.header.Date}
070 *          <li>{@link Expect}
071 *          <li>{@link From}
072 *          <li>{@link Host}
073 *          <li>{@link IfMatch}
074 *          <li>{@link IfModifiedSince}
075 *          <li>{@link IfNoneMatch}
076 *          <li>{@link IfRange}
077 *          <li>{@link IfUnmodifiedSince}
078 *          <li>{@link MaxForwards}
079 *          <li>{@link Pragma}
080 *          <li>{@link ProxyAuthorization}
081 *          <li>{@link Range}
082 *          <li>{@link Referer}
083 *          <li>{@link TE}
084 *          <li>{@link UserAgent}
085 *          <li>{@link Upgrade}
086 *          <li>{@link Via}
087 *          <li>{@link Warning}
088 *          <li>{@link TimeZone}
089 *       </ul>
090 *    <li>Other objects:
091 *       <ul class='javatreec'>
092 *          <li>{@link ResourceBundle}
093 *          <li>{@link Messages}
094 *          <li>{@link InputStream}
095 *          <li>{@link ServletInputStream}
096 *          <li>{@link Reader}
097 *          <li>{@link OutputStream}
098 *          <li>{@link ServletOutputStream}
099 *          <li>{@link Writer}
100 *          <li>{@link RequestHeaders}
101 *          <li>{@link RequestQueryParams}
102 *          <li>{@link RequestFormParams}
103 *          <li>{@link RequestPathParams}
104 *          <li>{@link Logger}
105 *          <li>{@link RestContext}
106 *          <li>{@link org.apache.juneau.parser.Parser}
107 *          <li>{@link Locale}
108 *          <li>{@link Swagger}
109 *          <li>{@link RequestContent}
110 *          <li>{@link Config}
111 *          <li>{@link UriContext}
112 *          <li>{@link UriResolver}
113 *       </ul>
114 * </ul>
115 *
116 * <h5 class='figure'>Example:</h5>
117 * <p class='bjava'>
118 *    <ja>@Rest</ja>(...)
119 *    <jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {
120 *
121 *       <jc>// Log the result of the request.</jc>
122 *       <ja>@RestPostCall</ja>
123 *       <jk>public void</jk> onPostCall(RestResponse <jv>res</jv>, Logger <jv>logger</jv>) {
124 *          <jv>logger</jv>.fine(<js>Output {0} was set on the response."</js>, <jv>res</jv>.getOutput());
125 *       }
126 *    }
127 * </p>
128 *
129 * <h5 class='section'>Notes:</h5><ul>
130 *    <li class='note'>
131 *       The method should return <jk>void</jk> although if it does return any value, the value will be ignored.
132 *    <li class='note'>
133 *       The method should be <jk>public</jk> although other visibilities are valid if the security manager allows it.
134 *    <li class='note'>
135 *       Static methods can be used.
136 *    <li class='note'>
137 *       Multiple post-call methods can be defined on a class.
138 *       <br>Post-call methods on parent classes are invoked before post-call methods on child classes.
139 *       <br>The order of post-call method invocations within a class is alphabetical, then by parameter count, then by parameter types.
140 *    <li class='note'>
141 *       The method can throw any exception, although at this point it is too late to set an HTTP error status code.
142 *    <li class='note'>
143 *       Note that if you override a parent method, you probably need to call <code><jk>super</jk>.parentMethod(...)</code>.
144 *       <br>The method is still considered part of the parent class for ordering purposes even though it's
145 *       overridden by the child class.
146 * </ul>
147 *
148 * <h5 class='section'>See Also:</h5><ul>
149 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/LifecycleHooks">Lifecycle Hooks</a>
150 * </ul>
151 */
152@Target({METHOD,TYPE})
153@Retention(RUNTIME)
154@Inherited
155@Repeatable(RestPostCallAnnotation.Array.class)
156public @interface RestPostCall {
157
158    /**
159     * Optional description for the exposed API.
160     *
161     * @return The annotation value.
162     * @since 9.2.0
163     */
164    String[] description() default {};
165
166    /**
167    * Dynamically apply this annotation to the specified methods.
168    *
169    * <h5 class='section'>See Also:</h5><ul>
170    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
171    * </ul>
172    *
173    * @return The annotation value.
174    */
175   String[] on() default {};
176}