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.rest.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019
020import javax.servlet.http.*;
021
022import org.apache.juneau.rest.*;
023
024/**
025 * Identifies Java methods on a resource/servlet class that get invoked during particular lifecycle events of
026 * the servlet or REST call.
027 *
028 * <p>
029 * For example, if you want to add an initialization method to your resource:
030 * <p class='bcode w800'>
031 *    <ja>@Rest</ja>(...)
032 *    <jk>public class</jk> MyResource  {
033 *
034 *       <jc>// Our database.</jc>
035 *       <jk>private</jk> Map&lt;Integer,Object&gt; <jf>myDatabase</jf>;
036 *
037 *       <ja>@RestHook</ja>(<jsf>INIT</jsf>)
038 *       <jk>public void</jk> initMyDatabase(RestContextBuilder builder) <jk>throws</jk> Exception {
039 *          <jf>myDatabase</jf> = <jk>new</jk> LinkedHashMap&lt;&gt;();
040 *       }
041 *    }
042 * </p>
043 *
044 * <p>
045 * Or if you want to intercept REST calls:
046 * <p class='bcode w800'>
047 *    <ja>@Rest</ja>(...)
048 *    <jk>public class</jk> MyResource {
049 *
050 *       <jc>// Add a request attribute to all incoming requests.</jc>
051 *       <ja>@RestHook</ja>(<jsf>PRE_CALL</jsf>)
052 *       <jk>public void</jk> onPreCall(RestRequest req) {
053 *          req.setAttribute(<js>"foo"</js>, <js>"bar"</js>);
054 *       }
055 *    }
056 * </p>
057 *
058 * <p>
059 * The hook events can be broken down into two categories:
060 * <ul class='spaced-list'>
061 *    <li>Resource lifecycle events:
062 *       <ul>
063 *          <li>{@link HookEvent#INIT INIT} - Right before initialization.
064 *          <li>{@link HookEvent#POST_INIT POST_INIT} - Right after initialization.
065 *          <li>{@link HookEvent#POST_INIT_CHILD_FIRST POST_INIT_CHILD_FIRST} - Right after initialization, but run child methods first.
066 *          <li>{@link HookEvent#DESTROY DESTROY} - Right before servlet destroy.
067 *       </ul>
068 *    <li>REST call lifecycle events:
069 *       <ul>
070 *          <li>{@link HookEvent#START_CALL START_CALL} - At the beginning of a REST call.
071 *          <li>{@link HookEvent#PRE_CALL PRE_CALL} - Right before the <ja>@RestMethod</ja> method is invoked.
072 *          <li>{@link HookEvent#POST_CALL POST_CALL} - Right after the <ja>@RestMethod</ja> method is invoked.
073 *          <li>{@link HookEvent#END_CALL END_CALL} - At the end of the REST call after the response has been flushed.
074 *       </ul>
075 * </ul>
076 *
077 * <ul class='notes'>
078 *    <li>
079 *       The {@link RestServlet} class itself implements several convenience methods annotated with this annotation
080 *       that can be overridden directly:
081 *       <ul class='javatree'>
082 *          <li class='jac'>{@link RestServlet}
083 *          <ul>
084 *             <li class='jm'>{@link RestServlet#onInit(RestContextBuilder) onInit(RestContextBuilder)}
085 *             <li class='jm'>{@link RestServlet#onPostInit(RestContext) onPostInit(RestContext)}
086 *             <li class='jm'>{@link RestServlet#onPostInitChildFirst(RestContext) onPostInitChildFirst(RestContext)}
087 *             <li class='jm'>{@link RestServlet#onDestroy(RestContext) onDestroy(RestContext)}
088 *             <li class='jm'>{@link RestServlet#onStartCall(HttpServletRequest,HttpServletResponse) onStartCall(HttpServletRequest,HttpServletResponse)}
089 *             <li class='jm'>{@link RestServlet#onPreCall(RestRequest,RestResponse) onPreCall(RestRequest,RestResponse)}
090 *             <li class='jm'>{@link RestServlet#onPostCall(RestRequest,RestResponse) onPostCall(RestRequest,RestResponse)}
091 *             <li class='jm'>{@link RestServlet#onEndCall(HttpServletRequest,HttpServletResponse) onEndCall(HttpServletRequest,HttpServletResponse)}
092 *          </ul>
093 *       </ul>
094 * </ul>
095 *
096 *
097 * <ul class='seealso'>
098 *    <li class='link'>{@doc RestLifecycleHooks}
099 * </ul>
100 */
101@Documented
102@Target(METHOD)
103@Retention(RUNTIME)
104@Inherited
105public @interface RestHook {
106
107   /**
108    * The lifecycle event.
109    */
110   HookEvent value();
111}