org.apache.juneau.rest.annotation.HookEvent Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest.annotation;
import java.io.*;
import java.util.*;
import java.util.logging.*;
import javax.servlet.*;
import javax.servlet.http.*;
import org.apache.juneau.*;
import org.apache.juneau.config.*;
import org.apache.juneau.dto.swagger.*;
import org.apache.juneau.http.*;
import org.apache.juneau.internal.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.utils.*;
/**
* Identifies servlet and REST call lifecycle events which cause {@link RestHook @RestHook}-annotated Java methods
* to be called.
*
* See Also:
*
* - {@doc juneau-rest-server.Instantiation.LifecycleHooks}
*
*/
public enum HookEvent {
/**
* Identifies a method that should be called immediately after the HttpServlet.service(HttpServletRequest, HttpServletResponse)
* method is called.
*
*
* Note that you only have access to the raw request and response objects at this point.
*
*
* The list of valid parameter types are as follows:
*
* - Servlet request/response objects:
*
* - {@link HttpServletRequest}
*
- {@link HttpServletResponse}
*
*
*
* Example:
*
* @RestResource (...)
* public class MyResource extends BasicRestServlet {
*
* // Add a request attribute to all incoming requests.
* @RestHook (START_CALL )
* public void onStartCall(HttpServletRequest req) {
* req.setAttribute("foobar" , new FooBar());
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple START_CALL methods can be defined on a class.
*
START_CALL methods on parent classes are invoked before START_CALL methods on child classes.
*
The order of START_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception.
*
{@link RestException RestExceptions} can be thrown to cause a particular HTTP error status code.
*
All other exceptions cause an HTTP 500 error status code.
* -
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
START_CALL,
/**
* Identifies a method that gets called immediately before the @RestMethod annotated method gets called.
*
*
* At this point, the {@link RestRequest} object has been fully initialized, and all {@link RestGuard} and
* {@link RestMatcher} objects have been called.
*
*
* The list of valid parameter types are as follows:
*
* - Servlet request/response objects:
*
* - {@link HttpServletRequest}
*
- {@link HttpServletResponse}
*
* - Extended request/response objects:
*
* - {@link RestRequest}
*
- {@link RestResponse}
*
* - Header objects:
*
* - {@link Accept}
*
- {@link AcceptCharset}
*
- {@link AcceptEncoding}
*
- {@link AcceptLanguage}
*
- {@link Authorization}
*
- {@link CacheControl}
*
- {@link Connection}
*
- {@link ContentLength}
*
- {@link ContentType}
*
- {@link org.apache.juneau.http.Date}
*
- {@link Expect}
*
- {@link From}
*
- {@link Host}
*
- {@link IfMatch}
*
- {@link IfModifiedSince}
*
- {@link IfNoneMatch}
*
- {@link IfRange}
*
- {@link IfUnmodifiedSince}
*
- {@link MaxForwards}
*
- {@link Pragma}
*
- {@link ProxyAuthorization}
*
- {@link Range}
*
- {@link Referer}
*
- {@link TE}
*
- {@link UserAgent}
*
- {@link Upgrade}
*
- {@link Via}
*
- {@link Warning}
*
- {@link TimeZone}
*
* - Other objects:
*
* - {@link ResourceBundle}
*
- {@link MessageBundle}
*
- {@link InputStream}
*
- {@link ServletInputStream}
*
- {@link Reader}
*
- {@link OutputStream}
*
- {@link ServletOutputStream}
*
- {@link Writer}
*
- {@link RequestHeaders}
*
- {@link RequestQuery}
*
- {@link RequestFormData}
*
- {@link HttpMethod}
*
- {@link Logger}
*
- {@link JuneauLogger}
*
- {@link RestContext}
*
- {@link org.apache.juneau.parser.Parser}
*
- {@link Locale}
*
- {@link Swagger}
*
- {@link RequestPath}
*
- {@link RequestBody}
*
- {@link Config}
*
- {@link UriContext}
*
- {@link UriResolver}
*
*
*
* Example:
*
* @RestResource (...)
* public class MyResource extends BasicRestServlet {
*
* // Log the incoming request.
* @RestHook (PRE_CALL )
* public void onPreCall(Accept accept, Logger logger) {
* logger.fine("Accept {0} header found." , accept);
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple PRE_CALL methods can be defined on a class.
*
PRE_CALL methods on parent classes are invoked before PRE_CALL methods on child classes.
*
The order of PRE_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception.
*
{@link RestException RestExceptions} can be thrown to cause a particular HTTP error status code.
*
All other exceptions cause an HTTP 500 error status code.
* -
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
* -
* It's advisable not to mess around with the HTTP body itself since you may end up consuming the body
* before the actual REST method has a chance to use it.
*
*/
PRE_CALL,
/**
* Identifies a method that gets called immediately after the @RestMethod annotated method gets called.
*
*
* At this point, the output object returned by the method call has been set on the response, but
* {@link RestConverter RestConverters} have not yet been executed and the response has not yet been written.
*
*
* The list of valid parameter types are the same as {@link #PRE_CALL}.
*
*
Example:
*
* @RestResource (...)
* public class MyResource extends BasicRestServlet {
*
* // Log the result of the request.
* @RestHook (POST_CALL )
* public void onPostCall(RestResponse res, Logger logger) {
* logger.fine(Output {0} was set on the response." , res.getOutput());
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple POST_CALL methods can be defined on a class.
*
POST_CALL methods on parent classes are invoked before POST_CALL methods on child classes.
*
The order of POST_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception, although at this point it is too late to set an HTTP error status code.
*
-
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
POST_CALL,
/**
* Identifies a method that gets called right before we exit the servlet service method.
*
*
* At this point, the output has been written and flushed.
*
*
* The list of valid parameter types are as follows:
*
* - Servlet request/response objects:
*
* - {@link HttpServletRequest}
*
- {@link HttpServletResponse}
*
*
*
*
* The following attributes are set on the {@link HttpServletRequest} object that can be useful for logging purposes:
*
* "Exception" - Any exceptions thrown during the request.
* "ExecTime" - Execution time of the request.
*
*
* Example:
*
* @RestResource (...)
* public class MyResource extends BasicRestServlet {
*
* // Log the time it took to execute the request.
* @RestHook (END_CALL )
* public void onEndCall(HttpServletRequest req, Logger logger) {
* Exception e = (Exception)req.getAttribute("Exception" );
* Long execTime = (Long)req.getAttribute("ExecTime" );
* if (e != null )
* logger.warn(e, "Request failed in {0}ms." , execTime);
* else
* logger.fine("Request finished in {0}ms." , execTime);
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple END_CALL methods can be defined on a class.
*
END_CALL methods on parent classes are invoked before END_CALL methods on child classes.
*
The order of END_CALL method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception, although at this point it is too late to set an HTTP error status code.
*
-
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
END_CALL,
/**
* Identifies a method that gets called during servlet initialization.
*
*
* This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestContextBuilder}
* object has been created and initialized with the annotations defined on the class, but before the
* {@link RestContext} object has been created.
*
*
* The only valid parameter type for this method is {@link RestContextBuilder} which can be used to configure the servlet.
*
*
* An example of this is the PetStoreResource class that uses an init method to perform initialization
* of an internal data structure.
*
*
Example:
*
* @RestResource (...)
* public class PetStoreResource extends ResourceJena {
*
* // Our database.
* private Map<Integer,Pet> petDB ;
*
* @RestHook (INIT )
* public void onInit(RestContextBuilder builder) throws Exception {
* // Load our database from a local JSON file.
* petDB = JsonParser.DEFAULT .parse(getClass().getResourceAsStream("PetStore.json" ), LinkedHashMap.class , Integer.class , Pet.class );
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple INIT methods can be defined on a class.
*
INIT methods on parent classes are invoked before INIT methods on child classes.
*
The order of INIT method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception causing initialization of the servlet to fail.
*
-
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
INIT,
/**
* Identifies a method that gets called immediately after servlet initialization.
*
*
* This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestContext}
* object has been created.
*
*
* The only valid parameter type for this method is {@link RestContext} which can be used to retrieve information
* about the servlet.
*
*
Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple POST_INIT methods can be defined on a class.
*
POST_INIT methods on parent classes are invoked before POST_INIT methods on child classes.
*
The order of POST_INIT method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception causing initialization of the servlet to fail.
*
-
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
POST_INIT,
/**
* Identical to {@link #POST_INIT} except the order of execution is child-resources first.
*
*
* Use this annotation if you need to perform any kind of initialization on child resources before the parent resource.
*
*
* This method is called from within the {@link Servlet#init(ServletConfig)} method after the {@link RestContext}
* object has been created and after the {@link #POST_INIT} methods have been called.
*
*
* The only valid parameter type for this method is {@link RestContext} which can be used to retrieve information
* about the servlet.
*
*
Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple POST_INIT_CHILD_FIRST methods can be defined on a class.
*
POST_INIT_CHILD_FIRST methods on parent classes are invoked before POST_INIT_CHILD_FIRST methods on child classes.
*
The order of POST_INIT_CHILD_FIRST method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* The method can throw any exception causing initialization of the servlet to fail.
*
*/
POST_INIT_CHILD_FIRST,
/**
* Identifies a method that gets called during servlet destroy.
*
*
* This method is called from within the {@link Servlet#destroy()}.
*
*
* The only valid parameter type for this method is {@link RestContext}, although typically no arguments will
* be specified.
*
*
Example:
*
* @RestResource (...)
* public class PetStoreResource extends ResourceJena {
*
* // Our database.
* private Map<Integer,Pet> petDB ;
*
* @RestHook (DESTROY )
* public void onDestroy() {
* petDB = null ;
* }
* }
*
*
* Notes:
*
* -
* The method should return
void although if it does return any value, the value will be ignored.
* -
* The method should be
public although other visibilities are valid if the security manager allows it.
* -
* Static methods can be used.
*
-
* Multiple DESTROY methods can be defined on a class.
*
DESTROY methods on child classes are invoked before DESTROY methods on parent classes.
*
The order of DESTROY method invocations within a class is alphabetical, then by parameter count, then by parameter types.
* -
* In general, destroy methods should not throw any exceptions, although if any are thrown, the stack trace will be
* printed to
System.err.
* -
* Note that if you override a parent method, you probably need to call
super .parentMethod(...)
The method is still considered part of the parent class for ordering purposes even though it's
* overridden by the child class.
*
*/
DESTROY
}