001package Torello.HTML;
002
003import java.util.Hashtable;
004
005/**
006 * Used to report unbalanced HTML Tags within any Vectorized-HTML page or sub-page.
007 * 
008 * <BR /><BR />HTML that is 'balanced' is HTML that (for each and every non-singleton /
009 * non-self-closing tag) has an equal number of opening and closing elements.  As an example, if
010 * within an HTML page or snippet, there exists an unclosed {@code <DIV>} element, the
011 * balance-reporter might show four {@code <DIV>'s}, but only three {@code </DIV>'s}.  This would
012 * report a {@code 'DIV'} count of {@code '+1'}.
013 * 
014 * <BR /><BR />Read more about this variant of validity-checking in class {@link Balance}.
015 * 
016 * @see Balance
017 */
018public class BalancedHTMLException extends MalformedHTMLException
019{
020    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */
021    public static final long serialVersionUID = 1;
022
023    /** Creates a new {@code BalancedHTMLException} with no detail message.*/
024    public BalancedHTMLException()
025    { super(); }
026
027    /**
028     * Constructs a {@code BalancedHTMLException} with the specified detail message.
029     * 
030     * @param unbalancedTags This is a {@code HashMap} that should have been generated by
031     * {@link Balance#check(Vector)} and {@link Balance#checkNonZero(Hashtable)}.  This table
032     * is printed into this exception's error detail message.
033     * 
034     * <BR /><BR /><B STYLE='color:red;'>IMPORTANT:</B> If this parameter is left null, this
035     * exception's constructor will throw a {@code NullPointerException}!  If this table is
036     * empty, the detail message will look bizarre.
037     */
038    public BalancedHTMLException(Hashtable<String, Integer> unbalancedTags)
039    { super(MESSAGE("", unbalancedTags)); }
040
041    /**
042     * Constructs a {@code BalancedHTMLException} with the specified detail message.
043     * @param message the detail message.
044     * 
045     * @param unbalancedTags This is a {@code HashMap} that should have been generated by
046     * {@link Balance#check(Vector)} and {@link Balance#checkNonZero(Hashtable)}.  This table
047     * is printed into this exception's error detail message.
048     * 
049     * <BR /><BR /><B STYLE='color:red;'>IMPORTANT:</B> If this parameter is left null, this
050     * exception's constructor will throw a {@code NullPointerException}!  If this table is
051     * empty, the detail message will look bizarre.
052     */
053    public BalancedHTMLException(String message, Hashtable<String, Integer> unbalancedTags)
054    { super(MESSAGE(message, unbalancedTags)); }
055
056    //  This just prints the balance report to the exceptions message.
057    private static String MESSAGE(String message, Hashtable<String, Integer> unbalancedTags)
058    {
059        if (unbalancedTags.size() == 0) return
060            (((message != null) && (message.length() > 0)) ? (message + '\n') : "") +
061            "AN EMPTY HTML-TAG BALANCE-REPORT WAS PROVIDED TO THIS EXCEPTION'S CONSTRUCTOR.";
062
063        else return
064            (((message != null) && (message.length() > 0)) ? (message + '\n') : "") +
065            Balance.toStringBalance(Balance.checkNonZero(unbalancedTags));
066    }
067}