/*
** Module   : Reportable.java
** Abstract : API for delegating the tracking of a testable activity
**
** Copyright (c) 2009-2023, Golden Code Development Corporation.
**
** -#- -I- --Date-- ---------------------------------------Description----------------------------------------
** 001 GES 20090113 API for delegating tracking of a testable activity.
** 002 CA  20210906 The content for description and failure is wrapped only for web tests. 
** 003 TJD 20230119 Timeout multiplier and trace mode support
*/

/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU Affero General Public License for more details.
**
** You should have received a copy of the GNU Affero General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

package com.goldencode.harness;

import java.util.*;

/**
 * API for delegating the tracking of a testable activity.
 */
public interface Reportable
{
   /**
    * Check if the description and failure content needs to be wrapped.
    * 
    * @return   <code>false</code> by default.
    */
   public default boolean isWrappedContent()
   {
      return false;
   }
   
   /**
    * Get the current status of the testable activity.
    *
    * @return   The current status.
    */
   public Status getStatus();
   
   /**
    * Set the new status of the testable activity.
    *
    * @param    status
    *           New status for the testable activity.
    */
   public void setStatus(Status status);
   
   /**
    * Set the status for the testable activity and if there was a failure, set
    * the reason for that failure.
    *
    * @param    status
    *           New status for the testable activity.
    * @param    reason
    *           If <code>status</code> is {@link Status#FAILED} then any
    *           value for this will be stored as the cause.
    */
   public void setStatus(Status status, String reason);
   
   /**
    * Get the current dependency type of the testable activity.
    *
    * @return   The current dependency type.
    */
   public Dependency getDependency();
   
   /**
    * Set the dependency type of the testable activity.
    *
    * @param    type
    *           New dependency type for the testable activity.
    */
   public void setDependency(Dependency type);
   
   /**
    * Get the reason for the testable activity failure, if a failure has
    * occurred.
    *
    * @return   A description of the reason for a failure or <code>null</code>
    *           if the testable activity has not completed running or if there
    *           was no failure.
    */
   public String getReason();
   
   /**
    * Set the reason for the testable activity failure, if a failure has
    * occurred.
    *
    * @param    reason
    *           A description of the reason for a failure or <code>null</code>
    *           if the testable activity has not completed running or if there
    *           was no failure.
    */
   public void setReason(String reason);
   
   /**
    * Get the current time (in milliseconds since the epoch) at the start of
    * this testable activity.
    *
    * @return   The number of milliseconds.
    */
   public long getStartTime();
   
   /**
    * Set the current time (in milliseconds since the epoch) at the start of
    * this testable activity.
    *
    * @param    start
    *           The number of milliseconds.
    */
   public void setStartTime(long start);
   
   /**
    * Get the current time (in milliseconds since the epoch) at the end of
    * this testable activity.
    *
    * @return   The number of milliseconds.
    */
   public long getEndTime();
   
   /**
    * Set the current time (in milliseconds since the epoch) at the end of
    * this testable activity.
    *
    * @param    end
    *           The number of milliseconds.
    */
   public void setEndTime(long end);
   
   /**
    * Get the number of milliseconds that elapsed during this testable activity.
    *
    * @return   The number of milliseconds.
    */
   public long getElapsed();
   
   /**
    * Get the maximum number of milliseconds that this testable activity is allowed to run.
    * Valid for some of Tests only, -1 if not applicable
    * @return   The maximum number of milliseconds.
    */
   public long getMaxElapsed();
   
   /**
    * Get the short name for the testable activity.
    *
    * @return   A name of the testable activity.
    */
   public String getName();
   
   /**
    * Set the short name for the testable activity.
    *
    * @param    name
    *           A name of the testable activity.
    */
   public void setName(String name);
   
   /**
    * Get the verbose description of the testable activity.
    *
    * @return   A description of the testable activity.
    */
   public String getDescription();
   
   /**
    * Set the verbose description of the testable activity.
    *
    * @param    descr
    *           A description of the testable activity.
    */
   public void setDescription(String descr);
   
   /**
    * Get the frequency distribution of the status codes in the list of
    * results.
    *
    * @return   The current status code statistics or <code>null</code> if
    *           the statistics have not been calculated yet.
    */
   public StatusCounter getStatusCounter();
   
   /**
    * Calculate the frequency distribution of the status codes in the given
    * list of results.
    *
    * @param    list
    *           The results list.
    */
   public void calculateStatusCounter(List<? extends Reportable> list);
   
   /**
    * Get the URL to the HTML report for the testable activity.
    *
    * @return   The URL or <code>null</code> if the testable activity has not
    *           completed running or if the report has not yet been generated.
    */
   public String getURL();
   
   /**
    * Set the URL to the HTML report for the testable activity.
    *
    * @param    url
    *           The URL or <code>null</code> if the testable activity has not
    *           completed running or if the report has not yet been generated.
    */
   public void setURL(String url);
   
   /**
    * Get the failure mode.
    *
    * @return   The definition of how to respond if/when this activity fails.
    */
   public FailureMode getFailureMode();
   
   /**
    * Set the failure mode.
    *
    * @param    failMode
    *           The definition of how to respond if/when this activity fails.
    */
   public void setFailureMode(FailureMode failMode);
   
   /**
    * Get the short name for the thread on which the testable activity
    * executed.
    *
    * @return   The thread name.
    */
   public String getThreadName();
   
   /**
    * Set the short name for the thread on which the testable activity
    * executed.
    *
    * @param    thread
    *           The thread name.
    */
   public void setThreadName(String thread);
   
   /**
    * Get the number of sub-elements of the testable activity.
    *
    * @return   If the testable activity is a single atomic activity, then
    *           this will return 1. Otherwise, it will return the number of
    *           individual sub-elements to be executed in this activity.
    */
   public int getNumberOfElements();
   
   /**
    * Read the results of each test and aggregate any failing test causes
    * into a single string for display.
    *
    * @param    list
    *           The test results.
    * @param    sb
    *           Buffer in which to aggregate the failure reasons.
    * @param    num
    *           The number of failure reasons that are already in the buffer.
    *
    * @return   The total number of failure reasons in the buffer.
    */
   public int checkResults(List<? extends Reportable> list,
                           StringBuilder              sb,
                           int                        num);
}
