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<Integer,Object> <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<>(); 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}