package Torello.JavaDoc;

import com.sun.source.tree.Tree;

/**
 * Entity: Exhaustive list of all items that may be defined inside of a Java Type.
 * 
 * <BR /><BR />
 * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITY>
 */
public enum Entity
{
    /** Denotes Field(s) */
    FIELD(
        Torello.JavaDoc.Field.class,
        com.sun.source.tree.VariableTree.class,
        "FD",
        "==== FIELD SUMMARY ====",
        "==== FIELD DETAIL ===="
    ),

    /** Denotes Method(s). */
    METHOD(
        Torello.JavaDoc.Method.class,
        com.sun.source.tree.MethodTree.class,
        "MD",
        "==== METHOD SUMMARY ====",
        "==== METHOD DETAIL ===="
    ),

    /** Denotes Constructor(s). */
    CONSTRUCTOR(
        Torello.JavaDoc.Constructor.class,
        com.sun.source.tree.MethodTree.class,
        "CO",
        "==== CONSTRUCTOR SUMMARY ====",
        "==== CONSTRUCTOR DETAIL ===="
    ),

    /**
     * Used for the 'Elements' - which <I>must be located</I> inside an Annotation Definition - but 
     * <I>are not always required or mandatory</I>.  Only an <CODE>&#64;interface</CODE>
     * ({@code Annotation}) may have "Annotation Elements".
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Optional &amp; Required:</B>
     * 
     * <BR />Because there are two types of Annotation-Members (option &amp; required - where
     * <I>optional elements have a <CODE>default value</CODE> assigned!</I>), null is assigned to
     * the {@code String}-Field {@link #jdSummaryMarker}.
     * 
     * <BR /><BR />Java puts both types of Annotation-Members in the same details-section on a Java
     * Doc Web-Page.  Therefore there is only one Detail-Section HTML-Comment Marker, and that 
     * {@code public} &amp; {@code final} {@code String}-field (@link #jdDetailMarker) is non-null,
     * and provided by this constant.
     */
    ANNOTATION_ELEM(
        Torello.JavaDoc.AnnotationElem.class,
        com.sun.source.tree.MethodTree.class,
        "AE",
        null, // There are **TWO** Annotation-Member Summary-Sections (and, therefore, two markers)
        "==== ANNOTATION TYPE MEMBER DETAIL ===="
    ),

    /**
     * Used for the Enumerated-Constants.  These are the Java-Identifiers which may only be found
     * inside a Java {@code 'enum'}.
     */
    ENUM_CONSTANT(
        Torello.JavaDoc.EnumConstant.class,
        com.sun.source.tree.VariableTree.class,
        "EC",
        "==== ENUM CONSTANT SUMMARY ====",
        "==== ENUM CONSTANT DETAIL ===="
    ),

    /**
     * Denotes Static inner-class(es), inner-interface(s), inner-enums, etc.
     */
    INNER_CLASS(
        Torello.JavaDoc.NestedType.class,
        com.sun.source.tree.ClassTree.class,
        "NT",
        "==== NESTED CLASS SUMMARY ====",
        null    // Nested-Types / Inner-Classes get their full-and-complete own pages.  They do not
                // have a "Details Section".  (Therefore there is no HTML-Comment Marker for them!)
    );


    // ********************************************************************************************
    // ********************************************************************************************
    // Reflection / Type java.lang.Class public constants
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITYFIELD>
     * 
     * <BR /><BR />The <CODE>Class&lt;? extends {@link Declaration}&gt;</CODE> instance stored in
     * this <B>'Type Mirror'</B> field is just the actual <B>{@code java.lang.class}</B> of one of
     * the six CIET-Types.  Specifically this field will always evaluate to one of the following 
     * values:
     * 
     * <BR /><BR /><TABLE CLASS='JDBriefTable MONO-SPACE-TABLE'>
     *  <TR><TH>Constant</TH>                   <TH>Ugrader Reflection Class</TH></TR>
     *  <TR><TD>{@link METHOD}</TD>             <TD>{@link Method}{@code .class}</TD></TR>
     *  <TR><TD>{@link FIELD}</TD>              <TD>{@link Field}{@code .class}</TD></TR>
     *  <TR><TD>{@link CONSTRUCTOR}</TD>        <TD>{@link Constructor}{@code .class}</TD></TR>
     *  <TR><TD>{@link ENUM_CONSTANT}</TD>      <TD>{@link EnumConstant}{@code .class}</TD></TR>
     *  <TR><TD>{@link ANNOTATION_ELEM}</TD>    <TD>{@link AnnotationElem}{@code .class}</TD></TR>
     *  <TR><TD>{@link INNER_CLASS}</TD>        <TD>{@link NestedType}{@code .class}</TD></TR>
     * </TABLE>
     */
    public final Class<? extends Declaration> upgraderReflectionClass;

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=ENTITYFIELD>
     * 
     * <BR /><BR />The {@code Class<? extends Node>} instance stored in this <B>'Type Mirror'</B>
     * field is the actual <B>{@code java.lang.Class}</B> of the {@code com.sun.source.tree} Node
     * that is used to build this kind of {@code Entity}.  Specifically, this field will always
     * evaluate to one of the following <B>Java Class</B> values:
     * 
     * <BR /><BR /><TABLE ID=JDTYPESTABLE3 CLASS='JDBriefTable MONO-SPACE-TABLE'>
     *  <TR><TH>Constant</TH>                   <TH>Sun/Oracle Reflection Class</TH></TR>
     *  <TR><TD>{@link METHOD}</TD>             <TD>MethodTree.class</TD></TR>
     *  <TR><TD>{@link FIELD}</TD>              <TD>VariableTree.class</TD></TR>
     *  <TR><TD>{@link CONSTRUCTOR}</TD>        <TD>MethodTree.class</TD></TR>
     *  <TR><TD>{@link ENUM_CONSTANT}</TD>      <TD>VariableTree.class</TD></TR>
     *  <TR><TD>{@link ANNOTATION_ELEM}</TD>    <TD>MethodTree.class</TD></TR>
     *  <TR><TD>{@link INNER_CLASS}</TD>        <TD>ClassTree.class</TD></TR>
     * </TABLE>
     */
    public final Class<? extends Tree> oracleReflectionClass;

    /** Two character abbreviation-string for this {@code Entity}, usefull for CSS ID's */
    public final String abbrev;

    /**
     * For all constants in this {@code enum}, this field will contain an identical value to the
     * value returned by method {@link #jdSummaryMarker()} - <B><I>except</I></B> for the constant
     * named {@link #ANNOTATION_ELEM}.  For the {@code ANNOTATION_ELEM} constant, this field will
     * contain null.
     * 
     * <BR /><BR />(This is because there are two types of Annotation-Elements - <I>optional</I>
     * and <I>required</I> - and therefore two different markers for their respective Summary 
     * Sections on a Java-Doc Web-Page)
     * 
     * <BR /><BR />The {@code String}-values contained in this field are listed in the following
     * table:
     * 
     * <BR /><BR /><TABLE ID=JDSUMMMARKTABLE CLASS='JDBriefTable MONO-SPACE-TABLE'>
     *  <TR><TH>Constant</TH>                   <TH>JavaDoc HTML-Comment Summary-Marker</TH></TR>
     *  <TR><TD>{@link METHOD}</TD>             <TD>"==== METHOD SUMMARY ===="</TD></TR>
     *  <TR><TD>{@link FIELD}</TD>              <TD>"==== FIELD SUMMARY ===="</TD></TR>
     *  <TR><TD>{@link CONSTRUCTOR}</TD>        <TD>"==== CONSTRUCTOR SUMMARY ===="</TD></TR>
     *  <TR><TD>{@link ENUM_CONSTANT}</TD>      <TD>"==== ENUM CONSTANT SUMMARY ===="</TD></TR>
     *  <TR><TD>{@link ANNOTATION_ELEM}</TD>    <TD>null</TD></TR>
     *  <TR><TD>{@link INNER_CLASS}</TD>        <TD>"==== NESTED CLASS SUMMARY ===="</TD></TR>
     * </TABLE>
     * 
     * @see #jdSummaryMarker()
     */
    public final String jdSummaryMarker;

    /**
     * For all constants in this {@code enum}, this field will contain an identical value to the
     * value returned by method {@link #jdDetailMarker()} - <B><I>except</I></B> for the constant
     * named {@link #INNER_CLASS}.  For the {@code INNER_CLASS} constant, this field will contain
     * null.
     * 
     * <BR /><BR />(This is because Nested-Types do not have "Details Sections" on a Java-Doc 
     * Generated Web-Page.  Nested-Types get their own respective pages!)  When the method
     * {@link #jdDetailMarker()} is invoked on the {@link #INNER_CLASS} constant, that method will
     * simply throw an exception.
     *
     * <BR /><BR />The {@code String}-values contained in this field are listed in the following
     * table:
     * 
     * <BR /><BR /><TABLE ID=JDDETMARKTABLE CLASS='JDBriefTable MONO-SPACE-TABLE'>
     *  <TR><TH>Constant</TH>                   <TH>JavaDoc HTML-Comment Detail-Marker</TH></TR>
     *  <TR><TD>{@link METHOD}</TD>             <TD>"==== METHOD DETAIL ===="</TD></TR>
     *  <TR><TD>{@link FIELD}</TD>              <TD>"==== FIELD DETAIL ===="</TD></TR>
     *  <TR><TD>{@link CONSTRUCTOR}</TD>        <TD>"==== CONSTRUCTOR DETAIL ===="</TD></TR>
     *  <TR><TD>{@link ENUM_CONSTANT}</TD>      <TD>"==== ENUM CONSTANT DETAIL ===="</TD></TR>
     *  <TR><TD>{@link ANNOTATION_ELEM}</TD>    <TD>"==== ANNOTATION TYPE MEMBER DETAIL ===="
     *                                          </TD></TR>
     *  <TR><TD>{@link INNER_CLASS}</TD>        <TD>null</TD></TR>
     * </TABLE>
     * 
     * @see #jdDetailMarker()
     */
    public final String jdDetailMarker;

    /**
     * Inside the HTML of a Java-Doc Web-Page, each of the entities will have a summary section
     * that is demarcated by an HTML Comment to signal the beginning of that summary-section.
     * The contents of this HTML comment may be retrieved by calling this method.
     * 
     * <BR /><BR />This {@code 'enum'} also has a {@code public} field {@code String}-constant
     * with the same name as this method (a {@code public} &amp; {@code final} field of type
     * {@code String} named {@link #jdSummaryMarker}.  This field contains an identical 
     * {@code String} as the return-values for this method, <B><I>except</I></B> for the constant
     * named {@link #ANNOTATION_ELEM} (which is explained below).
     * 
     * @return The HTML Commennt Marker that Java-Doc uses to indicate the beginning of the HTML
     * <B><I>Summary Section</I></B> on a Java-Doc Generated Web-Page associated with
     * {@code 'this'} entity.
     * 
     * <BR /><BR />If this instance of {@code Entity} is the {@link #ANNOTATION_ELEM} instance,
     * then this method will throw an {@code UpgradeException}
     * 
     * <BR /><BR />The complete list of Summary-Section Begin Markers can be viewed in the
     * table-provided <B><A HREF='#JDSUMMMARKTABLE'>HERE</A></B>.
     * 
     * @throws UpgradeException If this method is invoked on the {@link ANNOTATION_ELEM} constant.
     * 
     * @see #jdSummaryMarker
     */
    public String jdSummaryMarker()
    {
        if (this == ANNOTATION_ELEM) throw new UpgradeException(
            "You have asked Entity.ANNOTATION_ELEM for the HTML Comment Summary Marker, but " +
            "this is not allowed because there are two kinds of Annotation Element Summaries.  " +
            "As such, there is no way to distinguish which Comment-Marker String is being " +
            "requeted.  An Annotation could have an 'Optional Annotation Element Summary', and " +
            "a 'Required Annotation Element Summary.'"

        );

        return jdSummaryMarker;
    }

    /**
     * 
     * @return The HTML Commennt Marker that Java-Doc uses to indicate the beginning of the HTML
     * <B><I>Detail Section</I></B> on a Java-Doc Generated Web-Page associated with {@code 'this'}
     * entity.
     * 
     * <BR /><BR />If this instance of {@code Entity} is the {@link #INNER_CLASS} instance, then
     * this method will throw an {@code UpgradeException}
     * 
     * <BR /><BR />The complete list of Detail-Section Begin Markers can be viewed in the
     * table-provided <B><A HREF='#JDDETMARKTABLE'>HERE</A></B>.
     * 
     * @throws UpgradeException If this method is invoked on the {@link INNER_CLASS} constant.
     * Java-Doc Generated Web-Pages simply do not have Details-Sections.  This is because Java-Doc
     * will create a full and separate page for inner-classes / nested-types.
     * 
     * @see #jdDetailMarker
     */
    public String jdDetailMarker()
    {
        if (this == INNER_CLASS) throw new UpgradeException(
            "Nested-Types simply do not have a Details-Section on a Java-Doc Web-Page (they " +
            "get their own page!)  Therefore there is no Detail-Section Start Comment-Marker " +
            "to provide here."
        );

        return jdDetailMarker;
    }

    /**
     * Checks whether {@code 'this'} is an instance that represents an entity that may be called or
     * invoked (and would, therefore, accept parameters as input).  In Java, both methods and
     * constructors may be invoked.
     * 
     * @return <CODE>TRUE</CODE> if {@code 'this'} instance is either the {@link #METHOD} or the
     * {@link #CONSTRUCTOR} constant.  Returns <CODE>FALSE</CODE> otherwise.
     */
    public boolean isCallable()
    { return (this == METHOD) || (this == CONSTRUCTOR); }

    // Private constructor
    private Entity(
            Class<? extends Declaration> upgraderReflectionClass,
            Class<? extends Tree> oracleReflectionClass,
            String abbrev,
            String jdSummaryMarker,
            String jdDetailMarker
        )
    {
        this.upgraderReflectionClass    = upgraderReflectionClass;
        this.oracleReflectionClass      = oracleReflectionClass;
        this.abbrev                     = abbrev;
        this.jdSummaryMarker            = jdSummaryMarker;
        this.jdDetailMarker             = jdDetailMarker;
    }
}