package Torello.Java;

import java.util.Vector;

/**
 * An exception that performs a little bit of passed-parameter checking for the class
 * {@code StrCmpr}.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXPM>
 */
public class StrCmprException 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 {@code class StrCmpr}.
     */
    public final Vector<String> compareStrVec;

    /** 
     * <EMBED CLASS='external-html' DATA-FILE-ID=EXPF>
     * 
     * <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 {@code 'message'}, and the two
     * {@code public, final} parameters: {@code compareStr} and {@code i}.
     * 
     * @param message This should be a well-formatted message informing the user what has occurred.
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were 
     * passed to the {@code class StrCmpr} methods 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 cause
     * the exception to throw.  This value must be between {@code 0} and
     * {@code comparestr.length - 1}, or {@link ExceptionCheckError} will throw.
     * 
     * @throws ExceptionCheckError If parameter {@code 'compareStr'} is passed null, or if
     * parameter {@code 'i'} is not a valid array-index into {@code 'compareStr'}.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public StrCmprException(String message, String[] compareStr, int i)
    {
        super(message);

        if (compareStr == null) throw new ExceptionCheckError
            ("StrCmprException constructor parameter 'compareStr' was passed null.");

        if ((i < 0) || (i >= compareStr.length)) throw new ExceptionCheckError(
            "StrmCmprException constructor parameter 'i' was passed a value that is not within " +
            "the bounds of the var-args String-array parameter 'comparestr'"
        );

        this.compareStrVec = new Vector<>();
        for (String s : compareStr) this.compareStrVec.add(s);

        this.i = i;
    }

    /**
     * Constructs a new exception with the specified detail {@code 'message'}, cause-chain
     * {@code Throwable}, and the two {@code public, final} parameters: {@code compareStr} and
     * {@code i}.
     * 
     * @param message This should be a well-formatted message informing the user what has occurred.
     * 
     * @param cause This is sometimes used to "chain" exceptions in multi-threaded or heavily
     * I/O related code.
     * 
     * @param compareStr This <I>SHOULD BE</I> the list of compare-{@code String's} that were
     * passed to a {@code class StrCmpr} method 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 cause
     * the exception to throw.  This value must be between {@code 0} and
     * {@code comparestr.length - 1}, or {@link ExceptionCheckError} will throw.
     * 
     * @throws ExceptionCheckError If parameter {@code 'compareStr'} is passed null, or if
     * parameter {@code 'i'} is not a valid array-index into {@code 'compareStr'}.
     * 
     * @see #compareStrVec
     * @see #i
     */
    public StrCmprException(String message, Throwable cause, String[] compareStr, int i)
    {
        super(message, cause);

        if (compareStr == null) throw new ExceptionCheckError
            ("StrCmprException constructor parameter 'compareStr' was passed null.");

        if ((i < 0) || (i >= compareStr.length)) throw new ExceptionCheckError(
            "StrmCmprException constructor parameter 'i' was passed a value that is not within " +
            "the bounds of the var-args String-array parameter 'comparestr'"
        );

        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 array}.
     *
     * <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 String[]} array-parameter that was
     * passed to a search method
     * 
     * @throws TCCompareStrException If any of the elements of {@code compareStr} are null, or if
     * the 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 StrCmprException(
            "You have passed zero-arguments to a StrCmpr 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 StrCmprException(
                "One of the compare-strings passed to a search-method's var-args String... parameter " +
                "was null.  This is not allowed.",
                compareStr, i
            );
    }
}