/*
    * 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.core.doc;
  
  import java.io.Serializable;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collections;
  import java.util.Iterator;
  import java.util.List;
  
  import net.jcip.annotations.GuardedBy;
  
  import org.apache.commons.lang.NullArgumentException;
  
  /**
   * The test documentation of a unit under test.
   *
   * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
   * @version $Revision:591 $
   */
  public final class UnitTestDoc implements Serializable, Comparable<UnitTestDoc>
  {
    // ********************************* Fields *********************************
  
    // --- constants ------------------------------------------------------------
  
    /**
     * The class version identifier.
     * <p>
     * The value of this constant is {@value}.
     * </p>
     */
    private static final long serialVersionUID = 1L;
  
    /**
     * The guard name for synchronization.
     */
    private static final String GUARD = "scenarios";
  
    // --- members --------------------------------------------------------------
  
    /**
     * The type of the unit-under-test.
     *
     * @serial
     */
    private final Type uutType;
  
    /**
     * The test documentation of the individual tests of the unit.
     *
     * @serial
     */
    private final List<ScenarioTestDoc> scenarios;
  
    // ****************************** Initializer *******************************
  
    // ****************************** Constructors ******************************
  
    /**
     * Convenience constructor with type name as a {@link String}.
     *
     * @param uutType the type of the unit-under-test.
     */
    public UnitTestDoc(final String uutType)
    {
      this(new Type(uutType), (List<ScenarioTestDoc>) null);
    }
  
    /**
     * Convenience constructor with only a type.
     *
     * @param uutType the type of the unit-under-test.
     */
    public UnitTestDoc(final Type uutType)
    {
      this(uutType, (List<ScenarioTestDoc>) null);
    }
  
    /**
     * Convenience constructor to allow adding a list of scenarios as varargs.
     *
     * @param uutType the type of the unit-under-test.
     * @param scenarios the test documentation of the individual tests of the
     *          unit.
    * @throws IllegalArgumentException if <code>uutType</code> is blank or a
    *           scenario is a null value.
    */
   public UnitTestDoc(final String uutType, final ScenarioTestDoc... scenarios)
     throws IllegalArgumentException
   {
     this(uutType, createScenarioList(scenarios));
   }
 
   /**
    * Convenience constructor to allow adding a list of scenarios with an UUT
    * type name as {@link String}.
    *
    * @param uutType the type of the unit-under-test.
    * @param scenarios the test documentation of the individual tests of the
    *          unit.
    * @throws IllegalArgumentException if <code>uutType</code> is blank or
    *           <code>method</code> is empty or contains only whitespaces.
    */
   public UnitTestDoc(final String uutType, final List<ScenarioTestDoc> scenarios)
     throws IllegalArgumentException
   {
     this(new Type(uutType), scenarios);
   }
 
   /**
    * Convenience constructor to allow adding a list of scenarios as varargs.
    *
    * @param uutType the type of the unit-under-test.
    * @param scenarios the test documentation of the individual tests of the
    *          unit.
    * @throws IllegalArgumentException if <code>uutType</code> is blank or a
    *           scenario is a null value.
    */
   public UnitTestDoc(final Type uutType, final ScenarioTestDoc... scenarios)
     throws IllegalArgumentException
   {
     this(uutType, createScenarioList(scenarios));
   }
 
   /**
    * Default constructor to allow adding a list of scenarios.
    *
    * @param uutType the type of the unit-under-test.
    * @param scenarios the test documentation of the individual tests of the
    *          unit.
    * @throws IllegalArgumentException if <code>uutType</code> is blank or
    *           <code>method</code> is empty or contains only whitespaces.
    */
   public UnitTestDoc(final Type uutType, final List<ScenarioTestDoc> scenarios)
     throws IllegalArgumentException
   {
     checkArguments(uutType);
 
     this.uutType = uutType;
     this.scenarios =
         scenarios != null ? new ArrayList<ScenarioTestDoc>(scenarios)
             : new ArrayList<ScenarioTestDoc>();
   }
 
   // ******************************** Methods *******************************
 
   // --- init ---------------------------------------------------------------
 
   private void checkArguments(final Type uutType)
     throws IllegalArgumentException
   {
     if (null == uutType)
     {
       throw new IllegalArgumentException(
           "The UUT type is required, but was 'null'.");
     }
   }
 
   private static List<ScenarioTestDoc> createScenarioList(
       final ScenarioTestDoc... scenarios) throws IllegalArgumentException
   {
     assert scenarios != null : "Scenarios must not be 'null'.";
 
     for (final ScenarioTestDoc scenario : scenarios)
     {
       if (scenario == null)
       {
         throw new IllegalArgumentException("Scenarios must not be 'null'.");
       }
     }
     return Arrays.asList(scenarios);
   }
 
   // --- get&set ------------------------------------------------------------
 
   /**
    * Returns the type of the unit-under-test.
    *
    * @return the type of the unit-under-test.
    */
   public Type getUutType()
   {
     return uutType;
   }
 
   /**
    * Returns the test documentation of the individual tests of the unit.
    *
    * @return the test documentation of the individual tests of the unit.
    */
   @GuardedBy(GUARD)
   public List<ScenarioTestDoc> getScenarios()
   {
     synchronized (scenarios)
     {
       return new ArrayList<ScenarioTestDoc>(scenarios);
     }
   }
 
   @GuardedBy(GUARD)
   public List<ScenarioTestDoc> getSortedScenarios()
   {
     final List<ScenarioTestDoc> defaultSort = new ArrayList<ScenarioTestDoc>();
     final List<ScenarioTestDoc> sortedList =
         new ArrayList<ScenarioTestDoc>(scenarios.size());
 
     synchronized (scenarios)
     {
       for (final ScenarioTestDoc scenario : scenarios)
       {
         if (scenario.getSortKey().isDefault())
         {
           defaultSort.add(scenario);
         }
         else
         {
           sortedList.add(scenario);
         }
       }
     }
 
     Collections.sort(sortedList);
     sortedList.addAll(defaultSort);
     return sortedList;
   }
 
   /**
    * Returns the number of registered scenarios.
    *
    * @return the number of registered scenarios.
    */
   @GuardedBy(GUARD)
   public int getScenarioCount()
   {
     synchronized (scenarios)
     {
       return scenarios.size();
     }
   }
 
   // --- business -------------------------------------------------------------
 
   /**
    * Adds the test documentation to the documentation of the unit-under-test.
    *
    * @param scenario the documentation to be added.
    */
   @GuardedBy(GUARD)
   public void addScenario(final ScenarioTestDoc scenario)
   {
     synchronized (scenarios)
     {
       if (!this.scenarios.contains(scenario))
       {
         this.scenarios.add(scenario);
       }
     }
   }
 
   /**
    * Adds all scenarios of the given test doc to this instance.
    *
    * @param testDoc the test doc whose UUT type is identical to this'.
    * @throws IllegalArgumentException if the UUT type of this instance is not
    *           identical to the passed one.
    */
   @GuardedBy(GUARD)
   public void addScenarios(final UnitTestDoc testDoc)
     throws IllegalArgumentException
   {
     if (this.uutType.equals(testDoc.getUutType()))
     {
       for (final ScenarioTestDoc scenario : testDoc.getScenarios())
       {
         addScenario(scenario);
       }
     }
     else
     {
       throw new IllegalArgumentException(
           "The names of the UUTs differ. This is '" + uutType
               + "' the passed value is '" + testDoc.getUutType() + "'.");
     }
   }
 
   /**
    * Removes all scenarios that are associated with the given test case.
    *
    * @param testCaseType the type of test case whose scenarios are to be
    *          removed.
    * @throws NullArgumentException if <code>testCaseType</code> is
    *           <code>null</code>.
    */
   @GuardedBy(GUARD)
   public void removeScenarios(final Type testCaseType)
     throws NullArgumentException
   {
     if (testCaseType == null)
     {
       throw new NullArgumentException("testCaseType");
     }
 
     synchronized (scenarios)
     {
       for (final Iterator<ScenarioTestDoc> i = scenarios.iterator(); i
           .hasNext();)
       {
         final ScenarioTestDoc scenario = i.next();
         final Type scenarioTestCaseType = scenario.getTestCaseType();
         if (testCaseType.equals(scenarioTestCaseType))
         {
           i.remove();
         }
       }
     }
   }
 
   // --- object basics --------------------------------------------------------
 
   /**
    * {@inheritDoc}
    *
    * @see java.lang.Comparable#compareTo(java.lang.Object)
    */
   @Override
   public int compareTo(final UnitTestDoc o)
   {
     return this.uutType.compareTo(o.uutType);
   }
 
   /**
    * Returns the hash code of the object.
    *
    * @return the hash code.
    */
   @Override
   public int hashCode()
   {
     return uutType.hashCode();
   }
 
   /**
    * Returns <code>true</code> if the given object is semantically equal to the
    * given object, <code>false</code> otherwise.
    *
    * @param object the instance to compare to.
    * @return <code>true</code> if the given object is semantically equal to the
    *         given object, <code>false</code> otherwise.
    */
   @Override
   @GuardedBy(GUARD)
   public boolean equals(final Object object)
   {
     if (this == object)
     {
       return true;
     }
     else if (object == null || getClass() != object.getClass())
     {
       return false;
     }
 
     final UnitTestDoc other = (UnitTestDoc) object;
 
     synchronized (scenarios)
     {
       return (this.uutType.equals(other.uutType) && this.scenarios
           .equals(other.scenarios));
     }
 
   }
 
   /**
    * Returns the string representation of the object.
    *
    * @return the string representation of the object.
    */
   @Override
   @GuardedBy(GUARD)
   public String toString()
   {
     final StringBuilder buffer = new StringBuilder();
 
     buffer.append("The scenarios of UUT '").append(this.uutType).append('\'')
         .append(" are:\n");
     synchronized (scenarios)
     {
       for (final ScenarioTestDoc scenario : scenarios)
       {
         buffer.append(scenario).append('\n');
       }
     }
     return buffer.toString();
   }
 }