/*

  * 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;

 /**

  * Filter base class that guarantees to be just executed once per request,

  * on any servlet container. It provides a {@link #doFilterInternal}

  * method with HttpServletRequest and HttpServletResponse arguments.

  * <p/>

  * The {@link #getAlreadyFilteredAttributeName} method determines how

  * to identify that a request is already filtered. The default implementation

  * is based on the configured name of the concrete filter instance.

  * <h3>Controlling filter execution</h3>

  * 1.2 introduced the {@link #isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse)} method and

  * {@link #isEnabled()} property to allow explicit controll over whether the filter executes (or allows passthrough)

  * for any given request.

  * <p/>

  * <b>NOTE</b> This class was initially borrowed from the Spring framework but has continued modifications.

  *

  * @since 0.1

  */

 public abstract class OncePerRequestFilter extends NameableFilter {

     /**

      * Private internal log instance.

      */

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

     /**

      * Suffix that gets appended to the filter name for the "already filtered" request attribute.

      *

      * @see #getAlreadyFilteredAttributeName

      */

     public static final String ALREADY_FILTERED_SUFFIX = ".FILTERED";

     /**

      * Determines generally if this filter should execute or let requests fall through to the next chain element.

      *

      * @see #isEnabled()

      */

     private boolean enabled = true; //most filters wish to execute when configured, so default to true

     /**

      * Returns {@code true} if this filter should <em>generally</em><b>*</b> execute for any request,

      * {@code false} if it should let the request/response pass through immediately to the next

      * element in the {@link FilterChain}.  The default value is {@code true}, as most filters would inherently need

      * to execute when configured.

      * <p/>

      * <b>*</b> This configuration property is for general configuration for any request that comes through

      * the filter.  The

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

      * method actually determines whether or not if the filter is enabled based on the current request.

      *

      * @return {@code true} if this filter should <em>generally</em> execute, {@code false} if it should let the

      * request/response pass through immediately to the next element in the {@link FilterChain}.

      * @since 1.2

      */

     public boolean isEnabled() {

         return enabled;

     }

     /**

      * Sets whether or not this filter <em>generally</em> executes for any request.  See the

      * {@link #isEnabled() isEnabled()} JavaDoc as to what <em>general</em> execution means.

      *

      * @param enabled whether or not this filter <em>generally</em> executes.

      * @since 1.2

      */

     public void setEnabled(boolean enabled) {

         this.enabled = enabled;

     }

     /**

      * This {@code doFilter} implementation stores a request attribute for

      * "already filtered", proceeding without filtering again if the

      * attribute is already there.

      *

      * @see #getAlreadyFilteredAttributeName

      * @see #shouldNotFilter

      * @see #doFilterInternal

      */

     public final void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)

             throws ServletException, IOException {

         String alreadyFilteredAttributeName = getAlreadyFilteredAttributeName();

         if ( request.getAttribute(alreadyFilteredAttributeName) != null ) {

             log.trace("Filter '{}' already executed.  Proceeding without invoking this filter.", getName());

             filterChain.doFilter(request, response);

         } else //noinspection deprecation

             if (/* added in 1.2: */ !isEnabled(request, response) ||

                 /* retain backwards compatibility: */ shouldNotFilter(request) ) {

             log.debug("Filter '{}' is not enabled for the current request.  Proceeding without invoking this filter.",

                     getName());

             filterChain.doFilter(request, response);

         } else {

             // Do invoke this filter...

             log.trace("Filter '{}' not yet executed.  Executing now.", getName());

             request.setAttribute(alreadyFilteredAttributeName, Boolean.TRUE);

             try {

                 doFilterInternal(request, response, filterChain);

             } finally {

                 // Once the request has finished, we're done and we don't

                 // need to mark as 'already filtered' any more.

                 request.removeAttribute(alreadyFilteredAttributeName);

             }

         }

     }

     /**

      * Returns {@code true} if this filter should filter the specified request, {@code false} if it should let the

      * request/response pass through immediately to the next element in the {@code FilterChain}.

      * <p/>

      * This default implementation merely returns the value of {@link #isEnabled() isEnabled()}, which is

      * {@code true} by default (to ensure the filter always executes by default), but it can be overridden by

      * subclasses for request-specific behavior if necessary.  For example, a filter could be enabled or disabled

      * based on the request path being accessed.

      * <p/>

      * <b>Helpful Hint:</b> if your subclass extends {@link org.apache.shiro.web.filter.PathMatchingFilter PathMatchingFilter},

      * you may wish to instead override the

      * {@link org.apache.shiro.web.filter.PathMatchingFilter#isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse, String, Object)

      * PathMatchingFilter.isEnabled(request,response,path,pathSpecificConfig)}

      * method if you want to make your enable/disable decision based on any path-specific configuration.

      *

      * @param request the incoming servlet request

      * @param response the outbound servlet response

      * @return {@code true} if this filter should filter the specified request, {@code false} if it should let the

      * request/response pass through immediately to the next element in the {@code FilterChain}.

      * @throws IOException in the case of any IO error

      * @throws ServletException in the case of any error

      * @see org.apache.shiro.web.filter.PathMatchingFilter#isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse, String, Object)

      * @since 1.2

      */

     @SuppressWarnings({"UnusedParameters"})

     protected boolean isEnabled(ServletRequest request, ServletResponse response) throws ServletException, IOException {

         return isEnabled();

     }

     /**

      * Return name of the request attribute that identifies that a request has already been filtered.

      * <p/>

      * The default implementation takes the configured {@link #getName() name} and appends "{@code .FILTERED}".

      * If the filter is not fully initialized, it falls back to the implementation's class name.

      *

      * @return the name of the request attribute that identifies that a request has already been filtered.

      * @see #getName

      * @see #ALREADY_FILTERED_SUFFIX

      */

     protected String getAlreadyFilteredAttributeName() {

         String name = getName();

         if (name == null) {

             name = getClass().getName();

         }

         return name + ALREADY_FILTERED_SUFFIX;

     }

     /**

      * Can be overridden in subclasses for custom filtering control,

      * returning <code>true</code> to avoid filtering of the given request.

      * <p>The default implementation always returns <code>false</code>.

      *

      * @param request current HTTP request

      * @return whether the given request should <i>not</i> be filtered

      * @throws ServletException in case of errors

      * @deprecated in favor of overriding {@link #isEnabled(javax.servlet.ServletRequest, javax.servlet.ServletResponse)}

      * for custom behavior.  This method will be removed in Shiro 2.0.

      */

     @Deprecated

     @SuppressWarnings({"UnusedDeclaration"})

     protected boolean shouldNotFilter(ServletRequest request) throws ServletException {

         return false;

     }

     /**

      * Same contract as for

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

      * but guaranteed to be invoked only once per request.

      *

      * @param request  incoming {@code ServletRequest}

      * @param response outgoing {@code ServletResponse}

      * @param chain    the {@code FilterChain} to execute

      * @throws ServletException if there is a problem processing the request

      * @throws IOException      if there is an I/O problem processing the request

      */

     protected abstract void doFilterInternal(ServletRequest request, ServletResponse response, FilterChain chain)

             throws ServletException, IOException;

 }