/*
    * Copyright 2010-2013 smartics, Kronseder & Reiner GmbH
    *
    * Licensed 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 de.smartics.testdoc.report.export.doc;
  
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collections;
  import java.util.List;
  
  import de.smartics.testdoc.core.doc.ScenarioTestDoc;
  
  /**
   * Filter on test cases based on categories.
   */
  public class SelectionFilter
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * Constant to define a filter to include or exclude everything.
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    public static final String ALL_FILTER = "ALL";
  
    /**
     * Standard filter that does include everything and exclude nothing.
     */
    public static final SelectionFilter STANDARD = new SelectionFilter();
  
    /**
     * Used to signal that everything that is not included, is excluded.
     */
    private static final List<Class<?>> ALL = null;
  
    // --- members --------------------------------------------------------------
  
    /**
     * The category names of test scenarios that should be included. If a scenario
     * is tagged by at least one of the mentioned filters, it will be displayed in
     * the report.
     * <p>
     * The category is specified as a JUnit <code>Category</code>.
     * </p>
     * <p>
     * Per default, if no filter category is specified, all categories are
     * included.
     * </p>
     */
    private final List<Class<?>> includeCategories;
  
    /**
     * The category names of test scenarios that should be excluded. If a scenario
     * is tagged by at least one of the mentioned filters, it will not be
     * displayed in the report.
     * <p>
     * The category is specified as a JUnit <code>Category</code>.
     * </p>
     * <p>
     * Per default, if no filter category is specified, categories deriving from
     * {@link de.smartics.testdoc.categories.Technical} will not be rendered.
     * </p>
     */
    private final List<Class<?>> excludeCategories;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Constructor for the singleton provided by this class.
     */
    private SelectionFilter()
    {
      this(Arrays.asList(ALL_FILTER), new ArrayList<String>());
    }
  
    /**
     * Default constructor.
     *
     * @param includeCategories the category names of test scenarios that should
     *          be included.
     * @param excludeCategories the category names of test scenarios that should
    *          be excluded.
    */
   public SelectionFilter(final List<String> includeCategories,
       final List<String> excludeCategories)
   {
     this.includeCategories = provideCategories(includeCategories);
     this.excludeCategories = provideCategories(excludeCategories);
   }
 
   // ****************************** Inner Classes *****************************
 
   // ********************************* Methods ********************************
 
   // --- init -----------------------------------------------------------------
 
   // --- get&set --------------------------------------------------------------
 
   // --- business -------------------------------------------------------------
 
   /**
    * Filters scenarios by their categories.
    *
    * @param scenarios the scenarios to filter.
    * @return the filtered scenarios.
    */
   public List<ScenarioTestDoc> filterScenarios(
       final List<ScenarioTestDoc> scenarios)
   {
     final List<ScenarioTestDoc> filtered =
         new ArrayList<ScenarioTestDoc>(scenarios.size());
     for (final ScenarioTestDoc scenario : scenarios)
     {
       final List<String> categories = scenario.getCategories();
       if (acceptsAllOf(categories))
       {
         filtered.add(scenario);
       }
     }
     return filtered;
   }
 
   /**
    * Checks if the scenario is accepted.
    *
    * @param scenario the scenario to check.
    * @return true when accepted false otherwise.
    */
   public boolean acceptScenario(final ScenarioTestDoc scenario)
   {
     return acceptsAllOf(scenario.getCategories());
   }
 
   /**
    * Checks if all categories are accepted.
    *
    * @param categories the categories to be accepted.
    * @return <code>true</code> if all categories are accepted,
    *         <code>false</code> if at least one category is rejected.
    */
   private boolean acceptsAllOf(final List<String> categories)
   {
     if (categories.isEmpty())
     {
       return excludeCategories != ALL; // NOPMD
     }
 
     for (final String category : categories)
     {
       if (!acceptCategory(category))
       {
         return false;
       }
     }
 
     return true;
   }
 
   /**
    * If there are no filter elements, a default filter is created.
    */
   private static List<Class<?>> provideCategories(
       final List<String> filterCategories) throws IllegalArgumentException
   {
     final List<Class<?>> categories = new ArrayList<Class<?>>();
     if (filterCategories != null)
     {
       for (final String categoryName : filterCategories)
       {
         if (ALL_FILTER.equals(categoryName))
         {
           return ALL;
         }
         try
         {
           final Class<?> category = Class.forName(categoryName);
           categories.add(category);
         }
         catch (final ClassNotFoundException e)
         {
           throw new IllegalArgumentException("Unknown category '"
                                              + categoryName + "'.", e);
         }
       }
     }
     return Collections.unmodifiableList(categories);
   }
 
   /**
    * Checks whether or not the category is accepted to display the so tagged
    * scenario.
    *
    * @param category the category in question. This is the fully qualified class
    *          name of the category.
    * @return <code>true</code> if the category is accepted to be displayed,
    *         <code>false</code> if it should not be displayed. If the
    *         <code>category</code> is not know to the system (that is the class
    *         cannot be found), the category is also accepted and
    *         <code>true</code> is returned.
    */
   public boolean acceptCategory(final String category)
   {
     try
     {
       final Class<?> type = Class.forName(category);
       if (excludeCategories == ALL) // NOPMD
       {
         return acceptIncludes(type);
       }
       else
       {
         for (Class<?> excluded : excludeCategories)
         {
           if (excluded.isAssignableFrom(type))
           {
             return acceptIncludes(type);
           }
         }
         return true;
       }
     }
     catch (final ClassNotFoundException e)
     {
       return true;
     }
   }
 
   private boolean acceptIncludes(final Class<?> type)
   {
     if (includeCategories == ALL) // NOPMD
     {
       return true;
     }
 
     for (Class<?> included : includeCategories)
     {
       if (included.isAssignableFrom(type))
       {
         return true;
       }
     }
     return false;
   }
 
   /**
    * Filters the list of categories to retain only those that are accepted by
    * {@link #acceptCategory(String)}.
    *
    * @param categories the category list to filter.
    * @return a copy of the given <code>categories</code> containing only those
    *         categories that are accepted.
    */
   public List<String> filterCategories(final List<String> categories)
   {
     if (categories == null)
     {
       return null;
     }
 
     if (excludeCategories != ALL && excludeCategories.isEmpty()) // NOPMD
     {
       return new ArrayList<String>(categories);
     }
 
     final List<String> copy = new ArrayList<String>(categories.size());
     for (final String category : categories)
     {
       if (acceptCategory(category))
       {
         copy.add(category);
       }
     }
     return copy;
   }
 
   // --- object basics --------------------------------------------------------
 
 }