/*

  * 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.shiro.web.servlet;

 import org.slf4j.Logger;

 import org.slf4j.LoggerFactory;

 import javax.servlet.FilterChain;

 import javax.servlet.ServletException;

 import javax.servlet.ServletRequest;

 import javax.servlet.ServletResponse;

 import java.io.IOException;

 /**

  * A Servlet Filter that enables AOP-style "around" advice for a ServletRequest via

  * {@link #preHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) preHandle},

  * {@link #postHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) postHandle},

  * and {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) afterCompletion}

  * hooks.

  *

  * @since 0.9

  */

 public abstract class AdviceFilter extends OncePerRequestFilter {

     /**

      * The static logger available to this class only

      */

     private static final Logger log = LoggerFactory.getLogger(AdviceFilter.class);

     /**

      * Returns {@code true} if the filter chain should be allowed to continue, {@code false} otherwise.

      * It is called before the chain is actually consulted/executed.

      * <p/>

      * The default implementation returns {@code true} always and exists as a template method for subclasses.

      *

      * @param request  the incoming ServletRequest

      * @param response the outgoing ServletResponse

      * @return {@code true} if the filter chain should be allowed to continue, {@code false} otherwise.

      * @throws Exception if there is any error.

      */

     protected boolean preHandle(ServletRequest request, ServletResponse response) throws Exception {

         return true;

     }

     /**

      * Allows 'post' advice logic to be called, but only if no exception occurs during filter chain execution.  That

      * is, if {@link #executeChain executeChain} throws an exception, this method will never be called.  Be aware of

      * this when implementing logic.  Most resource 'cleanup' behavior is often done in the

      * {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) afterCompletion(request,response,exception)}

      * implementation, which is guaranteed to be called for every request, even when the chain processing throws

      * an Exception.

      * <p/>

      * The default implementation does nothing (no-op) and exists as a template method for subclasses.

      *

      * @param request  the incoming ServletRequest

      * @param response the outgoing ServletResponse

      * @throws Exception if an error occurs.

      */

     @SuppressWarnings({"UnusedDeclaration"})

     protected void postHandle(ServletRequest request, ServletResponse response) throws Exception {

     }

     /**

      * Called in all cases in a {@code finally} block even if {@link #preHandle preHandle} returns

      * {@code false} or if an exception is thrown during filter chain processing.  Can be used for resource

      * cleanup if so desired.

      * <p/>

      * The default implementation does nothing (no-op) and exists as a template method for subclasses.

      *

      * @param request   the incoming ServletRequest

      * @param response  the outgoing ServletResponse

      * @param exception any exception thrown during {@link #preHandle preHandle}, {@link #executeChain executeChain},

      *                  or {@link #postHandle postHandle} execution, or {@code null} if no exception was thrown

      *                  (i.e. the chain processed successfully).

      * @throws Exception if an error occurs.

      */

     @SuppressWarnings({"UnusedDeclaration"})

     public void afterCompletion(ServletRequest request, ServletResponse response, Exception exception) throws Exception {

     }

     /**

      * Actually executes the specified filter chain by calling <code>chain.doFilter(request,response);</code>.

      * <p/>

      * Can be overridden by subclasses for custom logic.

      *

      * @param request  the incoming ServletRequest

      * @param response the outgoing ServletResponse

      * @param chain    the filter chain to execute

      * @throws Exception if there is any error executing the chain.

      */

     protected void executeChain(ServletRequest request, ServletResponse response, FilterChain chain) throws Exception {

         chain.doFilter(request, response);

     }

     /**

      * Actually implements the chain execution logic, utilizing

      * {@link #preHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) pre},

      * {@link #postHandle(javax.servlet.ServletRequest, javax.servlet.ServletResponse) post}, and

      * {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) after}

      * advice hooks.

      *

      * @param request  the incoming ServletRequest

      * @param response the outgoing ServletResponse

      * @param chain    the filter chain to execute

      * @throws ServletException if a servlet-related error occurs

      * @throws IOException      if an IO error occurs

      */

     public void doFilterInternal(ServletRequest request, ServletResponse response, FilterChain chain)

             throws ServletException, IOException {

         Exception exception = null;

         try {

             boolean continueChain = preHandle(request, response);

             if (log.isTraceEnabled()) {

                 log.trace("Invoked preHandle method.  Continuing chain?: [" + continueChain + "]");

             }

             if (continueChain) {

                 executeChain(request, response, chain);

             }

             postHandle(request, response);

             if (log.isTraceEnabled()) {

                 log.trace("Successfully invoked postHandle method");

             }

         } catch (Exception e) {

             exception = e;

         } finally {

             cleanup(request, response, exception);

         }

     }

     /**

      * Executes cleanup logic in the {@code finally} code block in the

      * {@link #doFilterInternal(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain) doFilterInternal}

      * implementation.

      * <p/>

      * This implementation specifically calls

      * {@link #afterCompletion(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Exception) afterCompletion}

      * as well as handles any exceptions properly.

      *

      * @param request  the incoming {@code ServletRequest}

      * @param response the outgoing {@code ServletResponse}

      * @param existing any exception that might have occurred while executing the {@code FilterChain} or

      *                 pre or post advice, or {@code null} if the pre/chain/post execution did not throw an {@code Exception}.

      * @throws ServletException if any exception other than an {@code IOException} is thrown.

      * @throws IOException      if the pre/chain/post execution throw an {@code IOException}

      */

     protected void cleanup(ServletRequest request, ServletResponse response, Exception existing)

             throws ServletException, IOException {

         Exception exception = existing;

         try {

             afterCompletion(request, response, exception);

             if (log.isTraceEnabled()) {

                 log.trace("Successfully invoked afterCompletion method.");

             }

         } catch (Exception e) {

             if (exception == null) {

                 exception = e;

             } else {

                 log.debug("afterCompletion implementation threw an exception.  This will be ignored to " +

                         "allow the original source exception to be propagated.", e);

             }

         }

         if (exception != null) {

             if (exception instanceof ServletException) {

                 throw (ServletException) exception;

             } else if (exception instanceof IOException) {

                 throw (IOException) exception;

             } else {

                 if (log.isDebugEnabled()) {

                     String msg = "Filter execution resulted in an unexpected Exception " +

                             "(not IOException or ServletException as the Filter API recommends).  " +

                             "Wrapping in ServletException and propagating.";

                     log.debug(msg);

                 }

                 throw new ServletException(exception);

             }

         }

     }

 }