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