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