Package com.twelvemonkeys.servlet

Class GenericFilter

  • All Implemented Interfaces:
    java.io.Serializable, javax.servlet.Filter, javax.servlet.FilterConfig
    Direct Known Subclasses:
    BrowserHelperFilter, CacheFilter, FileUploadFilter, GZIPFilter, ImageFilter, ThrottleFilter, TimingFilter, TrimWhiteSpaceFilter
    public abstract class GenericFilter
extends java.lang.Object
implements javax.servlet.Filter, javax.servlet.FilterConfig, java.io.Serializable
    Defines a generic, protocol-independent filter.

    GenericFilter is inspired by GenericServlet, and implements the Filter and FilterConfig interfaces.

    GenericFilter makes writing filters easier. It provides simple versions of the lifecycle methods init and destroy and of the methods in the FilterConfig interface. GenericFilter also implements the log methods, declared in the ServletContext interface.

    GenericFilter has an auto-init system, that automatically invokes the method matching the signature void setX(<Type>), for every init-parameter x. Both camelCase and lisp-style parameter naming is supported, lisp-style names will be converted to camelCase. Parameter values are automatically converted from string representation to most basic types, if necessary.

    To write a generic filter, you need only override the abstract doFilterImpl(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain) doFilterImpl} method.

    Version:
    $Id: GenericFilter.java#1 $
    Author:
    Harald Kuhr, last modified by $Author: haku $
    See Also:
    Filter, FilterConfig, Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected boolean oncePerRequest
      Indicates if this filter should run once per request (true), or for each forward/include resource (false).

    • Constructor Summary

      Constructors 
      Constructor Description
      GenericFilter()
      Does nothing.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void destroy()
      Called by the web container to indicate to a filter that it is being taken out of service.
      void doFilter​(javax.servlet.ServletRequest pRequest, javax.servlet.ServletResponse pResponse, javax.servlet.FilterChain pFilterChain)
      The doFilter method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.
      protected abstract void doFilterImpl​(javax.servlet.ServletRequest pRequest, javax.servlet.ServletResponse pResponse, javax.servlet.FilterChain pChain)
      Invoked once, or each time a request/response pair is passed through the chain, depending on the oncePerRequest member variable.
      javax.servlet.FilterConfig getFilterConfig()
      Gets the FilterConfig for this filter.
      java.lang.String getFilterName()
      Returns the filter-name of this filter as defined in the deployment descriptor.
      java.lang.String getInitParameter​(java.lang.String pKey)
      Returns a String containing the value of the named initialization parameter, or null if the parameter does not exist.
      java.util.Enumeration getInitParameterNames()
      Returns the names of the servlet's initialization parameters as an Enumeration of String objects, or an empty Enumeration if the servlet has no initialization parameters.
      javax.servlet.ServletContext getServletContext()
      Returns a reference to the ServletContext in which the caller is executing.
      void init()
      A convenience method which can be overridden so that there's no need to call super.init(config).
      void init​(javax.servlet.FilterConfig pConfig)
      Called by the web container to indicate to a filter that it is being placed into service.
      protected void log​(java.lang.String pMessage)
      Writes the specified message to a servlet log file, prepended by the filter's name.
      protected void log​(java.lang.String pMessage, java.lang.Throwable pThrowable)
      Writes an explanatory message and a stack trace for a given Throwable to the servlet log file, prepended by the filter's name.
      void setFilterConfig​(javax.servlet.FilterConfig pFilterConfig)
      Deprecated.
      For compatibility only, use init instead.
      void setOncePerRequest​(boolean pOncePerRequest)
      Specifies if this filter should run once per request (true), or for each forward/include resource (false).

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • oncePerRequest

        protected boolean oncePerRequest
        Indicates if this filter should run once per request (true), or for each forward/include resource (false).

        Set this variable to true, to make sure the filter runs once per request.

        NOTE: As of Servlet 2.4, this field should always be left to it's default value (false).
        To run the filter once per request, the filter-mapping element of the web-descriptor should include a dispatcher element: 

        <dispatcher>REQUEST</dispatcher>

    • Constructor Detail

      • GenericFilter

        public GenericFilter()
        Does nothing.

    • Method Detail

      • init

        public void init​(javax.servlet.FilterConfig pConfig)
          throws javax.servlet.ServletException
        Called by the web container to indicate to a filter that it is being placed into service.

        This implementation stores the FilterConfig object it receives from the servlet container for later use. Generally, there's no reason to override this method, override the no-argument init instead. However, if you are overriding this form of the method, always call super.init(config).

        This implementation will also set all configured key/value pairs, that have a matching setter method annotated with InitParam.

        Specified by:
        init in interface javax.servlet.Filter
        Parameters:
        pConfig - the filter config
        Throws:
        javax.servlet.ServletException - if an error occurs during init
        See Also:
        Filter.init(javax.servlet.FilterConfig), init, BeanUtil.configure(Object, java.util.Map, boolean)

      • init

        public void init()
          throws javax.servlet.ServletException
        A convenience method which can be overridden so that there's no need to call super.init(config).
        Throws:
        javax.servlet.ServletException - if an error occurs during init
        See Also:
        init(FilterConfig)

      • doFilter

        public final void doFilter​(javax.servlet.ServletRequest pRequest,
                           javax.servlet.ServletResponse pResponse,
                           javax.servlet.FilterChain pFilterChain)
                    throws java.io.IOException,
                           javax.servlet.ServletException
        The doFilter method of the Filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.

        Subclasses should not override this method, but rather the abstract doFilterImpl(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain) doFilterImpl} method.

        Specified by:
        doFilter in interface javax.servlet.Filter
        Parameters:
        pRequest - the servlet request
        pResponse - the servlet response
        pFilterChain - the filter chain
        Throws:
        java.io.IOException
        javax.servlet.ServletException
        See Also:
        Filter.doFilter, doFilterImpl

      • doFilterImpl

        protected abstract void doFilterImpl​(javax.servlet.ServletRequest pRequest,
                                     javax.servlet.ServletResponse pResponse,
                                     javax.servlet.FilterChain pChain)
                              throws java.io.IOException,
                                     javax.servlet.ServletException
        Invoked once, or each time a request/response pair is passed through the chain, depending on the oncePerRequest member variable.
        Parameters:
        pRequest - the servlet request
        pResponse - the servlet response
        pChain - the filter chain
        Throws:
        java.io.IOException - if an I/O error occurs
        javax.servlet.ServletException - if an exception occurs during the filter process
        See Also:
        oncePerRequest, doFilter, Filter.doFilter

      • destroy

        public void destroy()
        Called by the web container to indicate to a filter that it is being taken out of service.
        Specified by:
        destroy in interface javax.servlet.Filter
        See Also:
        Filter.destroy()

      • getFilterName

        public java.lang.String getFilterName()
        Returns the filter-name of this filter as defined in the deployment descriptor.
        Specified by:
        getFilterName in interface javax.servlet.FilterConfig
        Returns:
        the filter-name
        See Also:
        FilterConfig.getFilterName()

      • getServletContext

        public javax.servlet.ServletContext getServletContext()
        Returns a reference to the ServletContext in which the caller is executing.
        Specified by:
        getServletContext in interface javax.servlet.FilterConfig
        Returns:
        the ServletContext object, used by the caller to interact with its servlet container
        See Also:
        FilterConfig.getServletContext(), ServletContext

      • getInitParameter

        public java.lang.String getInitParameter​(java.lang.String pKey)
        Returns a String containing the value of the named initialization parameter, or null if the parameter does not exist.
        Specified by:
        getInitParameter in interface javax.servlet.FilterConfig
        Parameters:
        pKey - a String specifying the name of the initialization parameter
        Returns:
        a String containing the value of the initialization parameter

      • getInitParameterNames

        public java.util.Enumeration getInitParameterNames()
        Returns the names of the servlet's initialization parameters as an Enumeration of String objects, or an empty Enumeration if the servlet has no initialization parameters.
        Specified by:
        getInitParameterNames in interface javax.servlet.FilterConfig
        Returns:
        an Enumeration of String objects containing the mNames of the servlet's initialization parameters

      • log

        protected void log​(java.lang.String pMessage)
        Writes the specified message to a servlet log file, prepended by the filter's name.
        Parameters:
        pMessage - the log message
        See Also:
        ServletContext.log(String)

      • log

        protected void log​(java.lang.String pMessage,
                   java.lang.Throwable pThrowable)
        Writes an explanatory message and a stack trace for a given Throwable to the servlet log file, prepended by the filter's name.
        Parameters:
        pMessage - the log message
        pThrowable - the exception
        See Also:
        ServletContext.log(String,Throwable)

      • setFilterConfig

        public void setFilterConfig​(javax.servlet.FilterConfig pFilterConfig)
        Deprecated.
        For compatibility only, use init instead.
        Initializes the filter.
        Parameters:
        pFilterConfig - the filter config
        See Also:
        init

      • getFilterConfig

        public javax.servlet.FilterConfig getFilterConfig()
        Gets the FilterConfig for this filter.
        Returns:
        the FilterConfig for this filter
        See Also:
        FilterConfig

      • setOncePerRequest

        @InitParam(name="once-per-request")
public void setOncePerRequest​(boolean pOncePerRequest)
        Specifies if this filter should run once per request (true), or for each forward/include resource (false). Called automatically from the init-method, with settings from web.xml.
        Parameters:
        pOncePerRequest - true if the filter should run only once per request
        See Also:
        oncePerRequest