package Torello.JavaDoc;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;

import Torello.Java.StrCmpr;

import java.util.*;

/**
 * Exception that may be thrown when erroneous-input is provided to internal-class
 * <B>{@code Details}</B> or <B>{@link ReflHTML}</B>.  These classes throw exceptions, rather than
 * printing errors to the messager, since they may be called, externally, by the end-users.  Those
 * classes are not strictly limited to internal-use.
 * 
 * @see ReflHTML
 */
public class DetailsException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /**
     * This is a helpful message explaining how to ensure that a sub-section of a vectorized-HTML
     * Documentation Web-Page is properly formatted according to the 'details' section of a
     * Java-Doc page.
     */
    protected static final String PLEASE_USE =
        "Please use the Details iterator(); Methods to retrieve a details section for a " +
        "Method, Field, Constructor or Enumerated-Constant.";

    /**
     * This is the message used for explaining how to retrieve an iterator of the 'details'
     * section for an Annotation Java-Doc page.
     */
    protected static final String PLEASE_USE_ANNOT =
        "Please use the Details iterator(); Methods to retrieve a details section for " +
        "the Annotation Elements.";

    /** Constructs a {@code DetailsException} with no detail message. */
    public DetailsException()
    { super(); }

    /**
     * Constructs a {@code DetailsException} with the specified detail message.
     * @param message the detail message.
     */
    public DetailsException(String message)
    { super(message); }

    /**
     * Constructs a new exception with the specified detail message and cause.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
     * 
     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
     * this exception's detail message.
     * 
     * @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.)
     */
    public DetailsException(String message, Throwable cause)
    { super(message, cause); }

    /**
     * Constructs a new exception with the specified cause and a detail message of
     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
     * detail message of cause).
     * 
     * <BR /><BR />This constructor is useful for exceptions that are little more than wrappers for
     * other throwables.
     * 
     * @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.)
     */
    public DetailsException(Throwable cause)
    { super(cause); }

    /**
     * This check method is used to ensure that a passed-parameter vectorized-HTML sub-page to one
     * of the {@code DetailsPartMethods, DetailsPartConstructors} or {@code DetailsPartFields} is a
     * properly formatted HTML Sub-Section. The purpose of the iterators within {@code class
     * Details} is to retrieve the <I>individual, detailed</I> descriptions for the fields, methods
     * and constructors from an HTML Page generated by the Java-Doc tool. This exception class will
     * do some <I>simple, basic</I> parameter checking to ensure that the proper parameters are
     * passed.  The priority is to provide more useable and meaningful error information.
     *
     * @param details This is supposed to be the return value from a call to the
     * {@code HNLIInclusive iter.next()} method.  The iterator should be one returned from the
     * {@code class Details} iterator' methods.  If it was, then it should a guarantee that the
     * section is properly formatted, because it would have been retrieved from a JavaDoc HTML
     * page.
     *
     * @throws DetailsException This exception shall throw if any of the requirements of the
     * section have not been met.
     * 
     * @see StrCmpr
     * @see TagNode
     */
    public static void check(Vector<HTMLNode> details)
    {
        TagNode first   = null;
        TagNode last    = null;

        // Ensure that the section is not null.
        if (details == null) throw new NullPointerException
            ("The vectorized-HTML section vector-reference was null.");

        // There should quite a number of elements in this vector, besides the beginning and
        // ending <UL>...</UL> elements.
        if (details.size() < 3) throw new DetailsException(
            "The vectorized-HTML section parameter has v.size()=" + details.size() +
            ".  This is not sufficient.  " + PLEASE_USE
        );

        // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        try
            { first = (TagNode) details.elementAt(0); }
        catch (ClassCastException e)
        { 
            throw new DetailsException(
                "This vectorized-HTML section does not begin with a TagNode element.  " +
                "It begins with [" + first.str + "]" + PLEASE_USE
            );
        }

        // All  Details Elements end with </ul>
        try
            { last = (TagNode) details.elementAt(details.size() - 1); }
        catch (ClassCastException e)
        {
            throw new DetailsException(
                "This vectorized-HTML section does not end with a TagNode element.  " + 
                "It ends with [" + last.str + "]" + PLEASE_USE
            );
        }

        // All  Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        if ((! first.tok.equals("ul")) || first.isClosing)
            throw new DetailsException(
                "The first node of the vectorized-HTML section is not an Opening <UL> Element.  " + 
                "It is a [" + first.str + "].  " + PLEASE_USE
            );

        // All  Details Elements end with </ul>
        if ((! last.tok.equals("ul")) || (! last.isClosing))
            throw new DetailsException(
                "The last node of the vectorized-HTML section is not a Closing </UL> Element.  " +
                "It is a [" + last.str + "].  " + PLEASE_USE
            );

        // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        if (! StrCmpr.containsOR_CI(first.AV("class"), "blockList", "blockListLast"))
            throw new DetailsException(
                "The first node of the vectorized-HTML section is not an Opening <UL> Element " +
                "with 'class' attribute containing string: 'blockList' or 'blockListLast.'  " +
                "Instead it is: [" + first.str + "]."
            );
    }

    /**
     * This check method is used to ensure that a passed-parameter vectorized-HTML sub-page is
     * correct.
     * 
     * <BR /><BR /><B STYLE='color:red;'>NOTE:</B> The Annotation-Element Details are just ever
     * so slightly different than they are for the other four types of details (Methods,
     * Constructors, Fields, and Enumerated-Constants).  The Annotation-Element Iterator returns
     * HTML {@code <SECTION>} elements instead!
     *
     * @param details This is supposed to be the return value from a call to the
     * {@code HNLIInclusive iter.next()} method.  The iterator should be one returned from the
     * {@code class Details} methods retreiving an Annotation-Element Iterator.
     *
     * @throws DetailsException This exception shall throw if any of the requirements of the
     * section have not been met.
     * 
     * @see StrCmpr
     * @see TagNode
     */
    public static void checkAnnotation(Vector<HTMLNode> details)
    {
        TagNode first   = null;
        TagNode last    = null;

        // Ensure that the section is not null.
        if (details == null) throw new NullPointerException
            ("The vectorized-HTML section vector-reference was null.");

        // There should quite a number of elements in this vector, besides the beginning and
        // ending <UL>...</UL> elements.
        if (details.size() < 3) throw new DetailsException(
            "The vectorized-HTML section parameter has v.size()=" + details.size() +
            ".  This is not sufficient.  " + PLEASE_USE
        );

        // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        try
            { first = (TagNode) details.elementAt(0); }
        catch (ClassCastException e)
        { 
            throw new DetailsException(
                "This vectorized-HTML section does not begin with a TagNode element.  " +
                "It begins with [" + first.str + "]" + PLEASE_USE_ANNOT
            );
        }

        // All  Details Elements end with </ul>
        try
            { last = (TagNode) details.elementAt(details.size() - 1); }
        catch (ClassCastException e)
        {
            throw new DetailsException(
                "This vectorized-HTML section does not end with a TagNode element.  " + 
                "It ends with [" + last.str + "]" + PLEASE_USE_ANNOT
            );
        }

        // All  Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        if ((! first.tok.equals("section")) || first.isClosing)
            throw new DetailsException(
                "The first node of the vectorized-HTML section is not an Opening <SECTION> " +
                "Element.  It is a [" + first.str + "].  " + PLEASE_USE_ANNOT
            );

        // All  Details Elements end with </ul>
        if ((! last.tok.equals("section")) || (! last.isClosing))
            throw new DetailsException(
                "The last node of the vectorized-HTML section is not a Closing </SECTION> " +
                "Element.  It is a [" + last.str + "].  " + PLEASE_USE_ANNOT
            );

        // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
        if (! StrCmpr.containsOR_CI(first.AV("role"), "region"))
            throw new DetailsException(
                "The first node of the vectorized-HTML section is not an Opening <SECTION> " +
                "element with 'role' attribute containing string: 'region.'  " +
                "Instead it is: [" + first.str + "]."
            );
    }
}