package Torello.HTML.NodeSearch;

import java.util.*;

import Torello.Java.ExceptionCheckError;

/**
 * <CODE>'Text-Comparitor Compare-String Exception'</CODE> is thrown by the argument marshalling
 * and validity checking code when attempts are made to search HTML-<CODE>Vector's</CODE> using
 * an invalid input-{@code String[]} parameter.
 * 
 * <BR /><BR />This class does some passed-parameter checking for the HTML-Search routines, such
 * as: {@code FIND, GET, REMOVE, POLL, etc...}  If one is using the class {@link TextComparitor},
 * it is important to remember that it usually works in coordination with Java's Varargs syntax
 * which allows anywhere from {@code '0'} to {@code 'n' String's}.
 * 
 * <BR /><BR />This class of {@code Exception} will be thrown if any one of them is null, or if
 * zero arguments were passed to the Varargs syntax.
 *
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXPM>
 */
public class TCCompareStrException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
     * 
     * <BR /><BR />This should contain the list of compare-{@code String's} passed for a parameter
     * list to a {@code TextComparitor}.
     */
    public final Vector<String> compareStrVec;

    /**
     * <BR /><BR />This field is intended to store the index into the {@code 'compareStrVec'} of
     * the compare-{@code String} that caused the exception throw in the first place.
     */
    public final int i;

    /**
     * Constructs a new exception with the specified detail message, and the two
     * {@code public, final} parameters: {@code compareStr} and {@code i}.
     * 
     * @param message the detail message.
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
     * passed to a {@code TextComparitor} that may have contained a null value, or was empty. 
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
     * 
     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that caused
     * the exception to throw.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public TCCompareStrException(String message, String[] compareStr, int i)
    {
        super(message);

        if (compareStr == null) throw new ExceptionCheckError
            ("Parameter 'compareStr' was passed a null reference");

        this.compareStrVec = new Vector<>();

        for (String s : compareStr) this.compareStrVec.add(s);

        this.i = i;
    }

    /**
     * Constructs a new exception with the specified detail message, cause-chain throwable, and the
     * two {@code public, final} parameters: {@code compareStr} and {@code i}.
     * 
     * @param message The detail message (which is saved for later retrieval by the
     * {@code Throwable.getMessage()} method).
     * 
     * @param cause the cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
     * passed to a {@code TextComparitor} that may have contained a null value, or was empty. 
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF_PARAM>
     * 
     * @param i This is the index into the {@code 'compareStr'} var-args parameter list that caused
     * the exception to throw.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public TCCompareStrException(String message, Throwable cause, String[] compareStr, int i)
    {
        super(message, cause);

        if (compareStr == null) throw new ExceptionCheckError
            ("Parameter 'compareStr' was passed a null reference");

        this.compareStrVec = new Vector<>();

        for (String s : compareStr) this.compareStrVec.add(s);

        this.i = i;
    }

    /**
     * This will do a simple test of the compare-{@code String's} to make sure none of them are
     * null, and that there are at least one {@code String} in the {@code String[] array}.
     *
     * <!-- This Explanation has been Copied from Torello.Java.StrCmprException -->
     * <BR /><BR /><B CLASS=JDDescLabel>Explanation:</B>
     * 
     * <BR />It is a subtle issue, but likely better to throw exceptions when one of the Varargs to
     * a {@code String} comparison is {@code 'null'}.  Since there is likely no general-convention
     * or agreement on what {@code null} in the presence of {@code logical AND, OR, NOT, XOR, NAND}
     * really means, throwing a {@code StrCmprException} <I>when even one var-args string-parameter
     * is {@code 'null'}</I> actually makes the most sense.
     * 
     * @param compareStr This should be the {@code var-args} parameter that was passed to a search
     * method
     * 
     * @throws TCCompareStrException If any of the elements of {@code 'compareStr'} is null, or if 
     * the {@code String[] array} is zero-length.
     */
    public static void check(String... compareStr)
    {
        if (compareStr == null) throw new NullPointerException
            ("The compareStr varags parameter, itself, was null.");

        if (compareStr.length == 0) throw new TCCompareStrException(
            "You have passed zero-arguments to a search-method's var-args String... " +
            "parameter.  You must pass at least one non-null compare-string",
            compareStr, 0
        );

        for (int i=0; i < compareStr.length; i++)
            if (compareStr[i] == null) throw new TCCompareStrException(
                "One of the compare-strings passed to a search-method's var-args " +
                "String... parameter was null.  This is not allowed.",
                compareStr, i
            );
    }
}