1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

package Torello.JavaDoc;

/**
 * CIET: Class, Interface, Enumerated-Type, Annotation (@interface) or Java 17+ Record.
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=CIET>
 */
public enum CIET
{
    /** Identifies that the associated file represents a java {@code 'class'} */
    CLASS("class"),

    /** Identifies that the associated file represents a java {@code 'interface'} */
    INTERFACE("interface"),

    /** Identifies that the associated file represents a java {@code 'enum'} (Enumerated-Type) */
    ENUM("enum"),
    
    /**
     * Identifies that the associated file represents a java {@code 'Annotation'}
     * ({@code @interface})
     */
    ANNOTATION("@interface"),

    /** Identifies that the associated file represents a (new, Java 14+) {@code 'record'}. */
    RECORD("record");

    /** The name of this CIET, as a String */
    private final String name;

    // private constructor, for the 'name' field
    private CIET(String name)
    { this.name   = name; }

    /**
     * Returns the name of this CIET, in string format.
     * 
     * @return Will return the name of this CIET as a String.  The actual string returned is, in
     * in all three cases, the restricted-java key-word that indicating whether this is a 'class'
     * 'interface' or 'enum' (Enumerated-Type) by returning <I><B>that exact String</I></B> as a
     * result when invoking this method.
     */
    public String toString() { return name; }

    /**
     * Returns the enum constant of this type with the specified name.
     * An invocation of {@code '.trim().toLowerCase()'} is performed, allowing white-space and
     * oddly capitalized names for the {@code String 'name'} parameter.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Note:</B>
     * 
     * <BR />Java's enumerated-type auto-generated method {@code 'valueOf(String name)'} may not be
     * over-ridden.  Unfortunately, the {@code String} provided to this method only permits /
     * tolerates {@code String's} that are identical to the exact-spelling of the enum-constant
     * itself.
     * 
     * <BR /><BR />For instance: {@code CIET.valueOf("CLASS")} returns the {@code 'CLASS'}
     * constant.  However if the string {@code 'class'} were passed, an
     * {@code 'IllegalArgumentException'} would be thrown.  In order to avoid this, this
     * method {@code get(String name)} is provided as an alternative, as it accepts
     * case-insensitive input.
     *
     * @param name This is the CIET name, as a String.
     * 
     * @return the CIET constant with the specified name
     * 
     * @throws NullPointerException if 'name' is null.
     * 
     * @throws IllegalArgumentException if, even after trim() and toLowerCase(), none of the CIET
     * names-as-Strings equal the specified input parameter 'name'
     */
    public static CIET get(String name)
    {
        switch (name.trim().toLowerCase())
        {
            case "class"        : return CLASS;
            case "interface"    : return INTERFACE;
            case "enum"         : return ENUM;
            case "@interface"   : return ANNOTATION;
            default             : throw new IllegalArgumentException(
                "There was no CIET associated with the provided string: [" + name + "]."
            );
        }
    }
}