001package Torello.HTML.Tools.JavaDoc;
002
003import com.github.javaparser.ast.body.*;
004
005/**
006 * CIET: Class, Interface, Enumerated-Type, Annotation (@interface) or Java 17+ Record.
007 * 
008 * <BR /><BR /><EMBED CLASS="external-html" DATA-FILE-ID="CIET">
009 */
010public enum CIET
011{
012    /** Identifies that the associated file represents a java {@code 'class'} */
013    CLASS("class", ClassOrInterfaceDeclaration.class),
014
015    /** Identifies that the associated file represents a java {@code 'interface'} */
016    INTERFACE("interface", ClassOrInterfaceDeclaration.class),
017
018    /** Identifies that the associated file represents a java {@code 'enum'} (Enumerated-Type) */
019    ENUM("enum", EnumDeclaration.class),
020    
021    /**
022     * Identifies that the associated file represents a java {@code 'Annotation'}
023     * ({@code @interface})
024     */
025    ANNOTATION("@interface", AnnotationDeclaration.class),
026
027    /** Identifies that the associated file represents a (new, Java 14+) {@code 'record'}. */
028    RECORD("record", null);
029
030    /** The name of this CIET, as a String */
031    private final String name;
032
033    /** The {@code java.lang.Class} of the Java Parser Type that is associated with this CIET. */
034    public final Class<? extends TypeDeclaration<?>> jpType;
035
036    // private constructor, for the 'name' field
037    private CIET(String name, Class<? extends TypeDeclaration<?>> jpType)
038    {
039        this.name   = name;
040        this.jpType = jpType;
041    }
042
043    /**
044     * Returns the name of this CIET, in string format.
045     * 
046     * @return Will return the name of this CIET as a String.  The actual string returned is, in
047     * in all three cases, the restricted-java key-word that indicating whether this is a 'class'
048     * 'interface' or 'enum' (Enumerated-Type) by returning <I><B>that exact String</I></B> as a
049     * result when invoking this method.
050     */
051    public String toString()    { return name; }
052
053    /**
054     * Returns the enum constant of this type with the specified name.
055     * An invocation of {@code '.trim().toLowerCase()'} is performed, allowing white-space and
056     * oddly capitalized names for the {@code String 'name'} parameter.
057     * 
058     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT NOTE:</B></SPAN> Java's enumerated-type
059     * auto-generated method {@code 'valueOf(String name)'} may not be over-ridden.  Unfortunately,
060     * the String provided to this method only permits/tolerates Strings that are identical to the
061     * exact-spelling of the enum-constant itself. For instance: {@code CIET.valueOf("CLASS")}
062     * returns enumerated-constant {@code CLASS}.  However if the string {@code 'class'} were
063     * passed, an {@code 'IllegalArgumentException'} would be thrown.  In order to avoid this, this
064     * method {@code get(String name)} is provided as an alternative.
065     *
066     * @param name This is the CIET name, as a String.
067     * 
068     * @return the CIET constant with the specified name
069     * 
070     * @throws NullPointerException if 'name' is null.
071     * 
072     * @throws IllegalArgumentException if, even after trim() and toLowerCase(), none of the CIET
073     * names-as-Strings equal the specified input parameter 'name'
074     */
075    public static CIET get(String name)
076    {
077        switch (name.trim().toLowerCase())
078        {
079            case "class"        : return CLASS;
080            case "interface"    : return INTERFACE;
081            case "enum"         : return ENUM;
082            case "@interface"   : return ANNOTATION;
083            default             : throw new IllegalArgumentException(
084                "There was no CIET associated with the provided string: [" + name + "]."
085            );
086        }
087    }
088}