package Torello.JavaDoc.Annotations;

import Torello.Java.Additional.Counter;
import Torello.Java.Additional.EffectivelyFinal;

import Torello.Java.StringParse;
import Torello.Java.StrCSV;

import java.util.Vector;
import java.util.Set;
import java.util.List;
import java.util.Iterator;

import javax.lang.model.element.Modifier;
import javax.lang.model.element.ElementKind;

import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.AnnotationValue;

import javax.tools.Diagnostic;
import javax.lang.model.util.SimpleElementVisitor8;

// EXPORTS:
//      public Excuse[] excuses() default {};
//      public String[] excused() default {};
// 
// Torello.JDUInternal.SimpleFeatures.StatelessClasses
//      This class is the "Work-Horse" for the Static-Function JDU-API User-Annotation.  This class
//      does the actual work of inserting an HTML-Message into a Java-Doc '.html'-File which 
//      explains that the User wants to inform his/her user's that a particular class/type does not
//      maintain any state.


@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="ANNOT_PROC_JDHBI")
public class SFProcessor
{
    private SFProcessor() { }

    // This is used by the Error-Message Printer
    private static final String SF_NAME = StaticFunctional.class.getSimpleName();

    // Some new "Multi-Threaded Java-Compiler" might break this class...
    // If there were multiple messagers in this imaginary-new multi-threaded compiler...
    // global-static non-final variable...

    private static javax.annotation.processing.Messager messager = null;


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Original Version used Reg-Ex's to parse Annotation-Elements.  These are all "Legacy" now...
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // Getting to know These Classes, and how to avoid importing them is what needed to happen.
    //      com.sun.tools.javac.code.Attribute$Constant
    //      com.sun.tools.javac.util.List
    //
    // When you ask for the Annotation-Element's, the above classes is what you will receive.
    // You have to take the good with the bad.  These classes aren't "that difficult" to deal with.
    // Since everything involving annotations is really ugly code, it needs "profuse commenting".
    // This was, for me, the straw that will break the back.


    /**
     * This implements the processing for the Annotation @{@link StaticFunctional}.  It does a lot
     * of validity checks on the parameter input.
     */
    static boolean process
        (Element ciet, AnnotationMirror am, javax.annotation.processing.Messager messager)
    {
        SFProcessor.messager = messager;

        boolean errors = false;

        ElementKind k = ciet.getKind();

        // @StaticFunctional may not be placed on an CIET.ENUM, nor a CIET.ANNOTATION nor a
        // CIET.RECORD.  In the actual annotation '.java' file the @StaticFunctional "thingy"
        // (where 'thingy' means StaticFunction.java - the definition, not the mirror nor the
        // the processor)... The file 'StaticFunctional.java' ... itself, has an annotation placed
        // on it that says:  @Target(ElementType.TYPE).  This means the javac compiler will allows
        // any '.java' file to have the @StaticFunctional Annotation placed on it.
        //
        // However, this annotation is only intended for Java-Classes and Java-Interfaces - and it
        // says so right there in the docs for the @StaticFunctional Annotation.  So if the
        // Annotation-Mirror does not report that this Annotation was placed on a CIET.CLASS or
        // a CIET.INTERFACE (but rather an enum, record or other annotation) - then tell the user
        // this is an error.
        //
        // Again, this error message is printed if the ElementKind is an ENUM, ANNOTATION or RECORD

        if ((k != ElementKind.CLASS) && (k != ElementKind.INTERFACE))
        {
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,     
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tOnly classes and interfaces can be annotated with @StaticFunctional\n" +
                ciet.toString() + " is neither of these, it is of kind: " + k.toString()
            );

            return true; // return errors = true;
        }

        // The "Excused()" String[]-Array that was passed by the user lists the names of the
        // fields that have been excused.  This is needed information during the processing-stage.
        // These will be saved inside a Vector.

        Vector<String> excused = new Vector<>();

        // The "Excuses()" Excuse[]-Array that the user may or may not pass are not needed right
        // now.  The JavaDoc Upgrader will use them when it upgrades the Java-Doc Web-Pages.  
        // Instead, all that is needed is the length of the array.  These two Annotation-Elements
        // (here called 'Members') must be parallel arrays with the same length; and if they are
        // not an error-message must be printed.
        //
        // NOTE: How cool is the "EffectivelyFinal" class from Torello.Java.Additional?
        //       (The 'for-each' loop body below is actually a "lambda-expression", and therefore
        //       requires that any variables which are used from outside the lambda-expression to
        //       be declared final or effectively-final)

        EffectivelyFinal<Integer> excusesCount = new EffectivelyFinal<>(0);

        am.getElementValues().forEach((ExecutableElement ee, AnnotationValue av) ->
        {
            // In the JavaDoc Web-Page Summaries Section, a "thingy" inside of an Annotation is
            // referred to as an Annotation-Element.  There are *BOTH* Optional *AND* Required
            // Annotation-Elements.  (In the JavaDoc-Upgrader these Elements are actually called
            // "Entities", and there is an enum-constant called Entity.ANNOTATION_ELEM)
            // 
            // In this part of "Java Annotations" (the actual Annotation-Processors), these are
            // referred to as "Members" - not "Elements", but they are the same thing.  These are
            // just the values that the user may provide, if he or she so chooses, when placing an
            // Annotation on a type/CIET.
            //
            // In the @StaticFunctional Annotation, the two "Member Names" are "Excuses" and
            // "Excused".  Both of their Values are Arrays... (One String[]-Array and one
            // Excuse[]-Array)

            String memberName   = ee.toString();
            Object memberValue  = av.getValue();


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // AND HERE-IN LIES THE TRUE-MADNESS.
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // "av.getValue()" returns an instance of: com.sun.tools.javac.util.List
            // And I have never heard of such a thing...
            //
            // Java Assertion.  This Really **SHOULD** Hold, but just in case....  There will be
            // a nice, warm & friendly reminder of how preposterous Java Annotation's really are.
            // They really could have done more work to 'sort-of' put-it all together.  The classes
            // we are supposed to use to actually do Annotation-Processing seem to be distributed
            // among HALF-A-DOZEN different Java-Packages...
            //
            // java.lang.annotation, javax.annotation.processing, javax.lang.model,
            // javax.lang.model.element, javax.tools, javax.lang.model.util,
            // 
            // AND-EVEN: com.sun.tools.javac.util.List  ... Which is not even in the JDK!!            

            if (! java.util.List.class.isAssignableFrom(memberValue.getClass()))

                // Don't use the Messager, this is a "Java-Error" (or else I'm just not quite
                // understanding Annotations-Processors yet)

                throw new InternalError(
                    memberName + " Annotation-Element-Value Type is not a java.util.List, " +
                    '[' + memberValue.getClass().getName() + ']'
                );


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Check if the "Entity/Member" is the Excused-Field Names List (A String[]-Array)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // Retrieve the names of the Excused Fields (they are String's inside of a
            // String[]-Array).  Save them to the Vector<String> that is/was declared at the very
            // top of this method.

            else if (memberName.equals("Excused()"))

                for (Object fieldName : (List) memberValue)

                    // The 'toString()' actually does include the quotation-marks in Java 11
                    // But in Java 17, the quotation-marks are gone!  The 'ifQuotesStripQuotes'
                    // method removes surrounding quotation-marks only if they are present.

                    excused.add(StringParse.ifQuotesStripQuotes(fieldName.toString()));


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Check if the "Entity/Member" is the Excuses List (An enum Excuse[]-Array)
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // Just retrieve how many Excuses there are, it is not important right now what the
            // excuses actually are, so long as the number provided is the same as the number of
            // fields for the 'Excused[]' Array.

            else if (memberName.equals("Excuses()"))
                excusesCount.f = ((List) memberValue).size();


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Unreachable Code.  javac will not compile extranneous Annotation-Elems
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            //
            // javac should flag this error before it ever reaches the Annotation-Processor.  Just
            // in case I missed something, throw an "InternalError" (don't use the messager)
            // 
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'

            else throw new InternalError(
                "\tThere was an annotation parameter whose name wasn't recognized: " +
                memberName.toString() + "\n" +
                "\tThe only parameter's that may be passed to @StaticFunctional " +
                    "are 'Excuses' and 'Excused'\n"
            );
        });


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Do the "Parallel Array" Check, first.
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This first checks that the same number of excuses and excused-fields were provided
        // (if any).  The "Excuses()" and "Excused()" Annotation-Elements (Entities) are supposed
        // to be parallel-arrays, whose lengths are equal.  If they are not, print an error
        // messsage.

        if (excusesCount.f != excused.size())
        {
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,     
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tYou have passed " + excused.size() + " excused field name" +
                ((excused.size() == 1) ? "" : "s") + ", " +
                "and " + excusesCount.f + " explanation" +
                ((excusesCount.f == 1) ? "" : "s") + " for " +
                ((excused.size() == 1) ? "that field" : "those fields") + ".\n" +
                "\tThe two optional array-parameters to the @StaticFunctional annotation must " +
                "be parallel-arrays, and when used, their lengths must be equal."
            );

            errors = true;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Check, first, whether or not "Excused Field Names" are all valid Java Identifiers
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This whole iterator-thing is needed to prevent multiple error messages about the same
        // mistaken field-name.  If a name is not a valid Java-Identifier, then an error message is
        // printed here.  There should be no reason to print a second error message later 
        // mentioning that that field name could not be found...
        //
        // Therefore, when not a valid Java-Identifier, the name of the Field should just be
        // removed, immediately, right here.  (The Iterator.remove() method removes it from the
        // underlying Vector<String>).
        //
        // NOTE: if it the field-name is not a valid Java-Identifier, there is no way it will be
        //       found as a "Member" of the Class or Interface...  And a second error message would
        //       be printed saying that the field-name wasn't found in the class (avoid this, by
        //       removing the field-name from the Vector)

        Iterator<String> excusedIter = excused.iterator();

        while (excusedIter.hasNext())

            if (! checkJavaIdentifier(ciet, excusedIter.next()))
            {
                errors = true;
                excusedIter.remove();
            }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // NOW: Iterate all the "Entities" (which Java calls "Elements") inside this CIET/Type
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // At this point, there may have already been errors.  The field names could be invalid
        // Java Identifiers and the arrays might not have been parallel.  However, there isn't
        // a reason to stop to printing more error messages.  Getting as many of these messages
        // out as possible is faster for the programmer.
        //
        // IMPORTANT: Any "additional" information passed to @StaticFunctional through the
        //            "Annotation-Elements" (Excused & Excuses), **CAN ONLY BE** for **FIELDS**
        //
        // This loop checks constructors, methods, and fields, and for the above mentioned reason,
        // this should should continue rather than quitting now - only to have a developer find
        // more errors the next time he tries to compile.

        int constructorCount = 0;

        // Again, here an "Element" is the "stuff" declared (at the 'top-level' so-to-speak) inside
        // of a Type (Class or Interface).  For the second time, I will repeat that in this JD
        // Upgrader Package, I actually call these "Entities" rather than "Elements", and the
        // "Entity" enum has FIELD'S, METHOD'S, CONSTRUCTOR'S, ANNOTATION_ELEM'S, ENUM_CONSTANT'S
        // and NESTED_TYPE'S
        //
        // Since this Type could only possibly be a Class or Interface, that rules out -
        // immediately, iterating ANNOTATION_ELEM's and ENUM_CONSTANTS...  (And Inner-Classes are
        // just irrelevant to the @StaticFunctional Annotation).  We only iterate Methods, Fields
        // and Constructors.
    
        for (Element e : ciet.getEnclosedElements())
        {
            // The Modifers are the words: public, private, protected, static, final, transient,
            // volatile etc...

            Set<Modifier> modifiers = e.getModifiers();

            switch (e.getKind())
            {
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // Inspects a Method, and makes sure it has been declared static
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                case METHOD :

                    // If it is not 'static' - print an the method 'modifierError' will print an
                    // error-message to the messager.  Make sure to update the 'errors' boolean
                    // flag.

                    if (! modifiers.contains(Modifier.STATIC))

                        errors |= modifierError(ElementKind.METHOD, Modifier.STATIC, ciet, e);

                    break;


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // Inspects a field, and ensure that it is both static & final -- or excused.
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                case FIELD :

                    boolean isExcused = excused.contains(e.getSimpleName().toString());

                    // NOTE: non-static fields **CANNOT** be excused, only non-final fields
                    if (! modifiers.contains(Modifier.STATIC))

                        errors |= modifierError(ElementKind.FIELD, Modifier.STATIC, ciet, e);

                    // If the field doesn't have the 'final' modifier, and it isn't excused, this
                    // is an error, and this is "kind-of" the **CORE** of @StaticFunctional
                    // This line right here, below, was (sort-of) the WHOLE-POINT of the Annotation
                    //
                    // ALSO: Making sure that all methods are declared static is, too, the
                    //       'WHOLE-POINT' (previous switch-case)

                    if (! modifiers.contains(Modifier.FINAL))
                    {
                        if (! isExcused)
                            errors |= fieldIsNotFinalButIsAlsoNotExcused(ciet, e);
                    }

                    // NOTE: This is a WARNING, not an ERROR.  This happens if they passed a field
                    //       name to "Excused()", that is already declared 'final' (so it doesn't
                    //       need to be listed as 'excused')
                    // 
                    // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'

                    else if (isExcused) messager.printMessage(
                        Diagnostic.Kind.WARNING,     
                        HELPER.LOCATION(ciet, SF_NAME) +
                        "\tField [" + e.getSimpleName().toString() + "] is declared excused; but" +
                        "this field is declared final, and therefore does not need to be excused."
                    );

                    // Remove this from the list... There is another error-check after this
                    // 'forEach' loop ends that checks if the user provided any field-names that
                    // weren't found as members / entities of the class.  That check is done by
                    // inspecting the 'excused' list (and if it isn't completely empty), then it
                    // prints the error-message that the field wasn't found.

                    if (isExcused) excused.remove(e.getSimpleName().toString());

                    break;


                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
                // Checks a constructor, and make sure it has zero-arguments, and is private
                // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

                case CONSTRUCTOR :

                    constructorCount++;

                    // NOTE: The static inner-class / nested-type "ZeeroArgConstructor" has a big
                    //       explanation for why it is needed - and this needs to be a separate
                    //       inner-class rather than a simple-check that is done right here inside
                    //       the switch-statement.
                    //
                    // The check requires counting the number of parameters to the constructor, but
                    // that information is completely-unavailable without using this "visitor".
                    //
                    // The method 'Element.accept(Visitor())' walks the Parse-Tree, and sends all
                    // of the Elements in the Parse-Tree to the Visitor-Handler's, User-Defined,
                    // Visit-Methods.  See the inner-class (defined below) for 'ZeroArgConstructor'
                    // to view the handler of a constructor-definition.
                    //
                    // NOTE: Building a 'Visitor' from an 'Adapter' in order to walk a Parse-Tree
                    //       using a 'walk' method (in this case, an 'accept' method) is the exact
                    //       same thing that the Java-Parser library does vis-a-vis AST Parse-Trees
                    //       and Tree-Walks with it's Visitor's and Visitor-Adapter classes.  Here
                    //       we are using the java.lang.model stuff-ola, instead.

                    if (e.accept(new ZeroArgContructor(messager, ciet), null)) errors = true;

                    // This 'if-branch' can only execute if this particular constructor has
                    // zero-args, and, yet, has not been declared private.  This is important for
                    // the "sinister" reason that the Java Auto-Generated Zero-Arg Constructor is
                    // **USUALLY** never actually something that the programmer typed into his 
                    // '.java' file.  
                    //
                    // This Error Messages reminds them of this tidbit of information... (auto
                    // added constructors that are placed into a class by 'javac' - The Java
                    // Compiler)

                    else if (! modifiers.contains(Modifier.PRIVATE))

                        errors |= modifierError
                            (ElementKind.CONSTRUCTOR, Modifier.PRIVATE, ciet, e);

                    break;

                default: break;

            }   // switch-statement: of the "Elements" inside this CIET/Type
                // which in JavaDoc-Upgrader-Speak are unfortunately called "Entities" instead

        } // For-Loop: Iterating the "Elements" of this CIET/Type


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // This make sure there aren't any 'extranneous' excused field-names
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // NOTE: In the loop above, whenever an "Element" (Java-Doc-Upgrader-Speak "Entities") is
        //       found by the switch-statement, above, it is removed from the Vector<String> that
        //       lists all of the "Excused" Fields (which aren't required to be 'final')
        //
        // So... If there are still field-names listed in the 'excused' list, then they are still
        // there because they were never found in the above for-loop-switch-statement, and that 
        // would be because they aren't actually fields inside the TYPE/CIET.

        if (excused.size() > 0)
        {
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,     
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tThere were fields listed as excused and non-final, but those fields were not " +
                "actually members of the " + ciet.getKind().toString().toLowerCase() + "." +
                "\n\tUn-Resolved Excused Feild-Names: " +
                StrCSV.toCSV(excused, s -> "[" + s + "]", false, null)
            );

            errors = true;
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Make sure there is only 1 constructor. 
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // This test is a little SUPERFLUOUS, otherwise one of the constructors would not have had
        // zero-arguments, and therefore would have been flagged (and mentioned) in the previous
        // loop that iterates all of the CIET/Type "Elements" ("Entities").  It  is a little
        // friendly reminder to myself (and them, I guess) - no more no less.

        if (constructorCount > 1)
        {
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,     
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tThere are " + constructorCount + " constructors.  There must be precisely " +
                "one private, zero-argument, constructor."
            );

            errors = true;
        }

        return errors;
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // This implements a "Visitor" for a Constructor
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // The only purpose of this class is to check that any constructors which are found, indeed
    // have precisely zero-arguments.  The primary need to make this a class is that it extends
    // the "SimpleElementVisitor8", which has a method that accept the "ExecutableElement."
    //
    // Having access to the "ExecutableElement" is actually the **ONLY WAY** to get the **NUMBER**
    // of parameters passed to a constructor.
    //
    // In the for-loop (above) that iterates the "Elements" ("Entities" - in JDU-Speak), none of 
    // the variables there actually have the ability to retrieve this information...  Again... this
    // "Visitor" Nested-Class is **ONLY** used on Elements which are Constructors.
    //
    // This is the "Inheritance Tree" for the Visitor:
    //  java.lang.Object
    //      javax.lang.model.util.AbstractElementVisitor6<R,P>
    //          javax.lang.model.util.SimpleElementVisitor6<R,P>
    //              javax.lang.model.util.SimpleElementVisitor7<R,P>
    //                  javax.lang.model.util.SimpleElementVisitor8<R,P>

    private static class ZeroArgContructor extends SimpleElementVisitor8<Boolean, Void>
    {
        private final javax.annotation.processing.Messager messager;
        private final Element ciet;

        ZeroArgContructor(javax.annotation.processing.Messager messager, Element ciet)
        { this.messager=messager;  this.ciet=ciet; }

        // This javax/lang/model/element/ElementVisitor has quite a few methods for visiting 
        // "stuff."  This is just one of several of them.  Again, this is only called when a
        // contructor is found, but it is also used on methods.  The "ExecutableElement" is the
        // parameter that makes this whole inner-class / Nested-Type useful-necessary.

        public Boolean visitExecutable(ExecutableElement exEl, Void v)
        {
            int paramCount = exEl.getParameters().size();

            if (paramCount > 0)
            {
                // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
                messager.printMessage(
                    Diagnostic.Kind.ERROR,     
                    HELPER.LOCATION(ciet, SF_NAME) +
                    "\tThere is a constructor with " + paramCount + " parameter" +
                    ((paramCount == 1) ? "" : "s") + ".  " +
                    "There must be precisely one private, zero-argument, constructor."
                );

                return true;
            }

            return false;
        }
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Checks that only valid Java Variable-Names are passed to the "Excused" Array-Parameter
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

    private static boolean checkJavaIdentifier(Element ciet, String fieldName)
    {
        // System.out.println(fieldName);

        if (fieldName.length() == 0)
        {
            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tString[]-Array Annotation-Parameter 'Excused' contains at least one " +
                "Zero-Length-String Element."
            );

            return false;
        }

        boolean passedTheTest = Character.isJavaIdentifierStart(fieldName.charAt(0));

        for (int i=1; passedTheTest && (i < fieldName.length()); i++)
            passedTheTest &= Character.isJavaIdentifierPart(fieldName.charAt(i));

        // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
        if (! passedTheTest) messager.printMessage(
            Diagnostic.Kind.ERROR,
            HELPER.LOCATION(ciet, SF_NAME) +
            "\tString[]-Array Paramter 'Excused()' indicates that a field named "+
                '[' + fieldName + "] is excused.\n" +
            "\tThis is not a valid Java Identifier, and therefore could not be a field."
        );

        return passedTheTest;
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Error Message for problems with the modifiers
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // Used on 'Constructors' if they don't have the 'private' modifier
    // Used on 'Fields' if they don't have the 'static' modifier
    // Used on 'Methods' if they don't have the 'static' modifier
    //
    // NOTE: There is no such thing as a 'static' contructor (hopefully that is obvious).
    //       Fields which lack the 'final' modifier, need a specialized error message. (below)

    private static boolean modifierError(ElementKind k, Modifier m, Element ciet, Element fcm)
    {
        if (k == ElementKind.CONSTRUCTOR)

            // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
            messager.printMessage(
                Diagnostic.Kind.ERROR,     
                HELPER.LOCATION(ciet, SF_NAME) +
                "\tThere is a constructor which was not declared private.  " +
                "Is it Java's zero-argument, auto-generated (synthetic) constructor?"
            );

        // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
        else messager.printMessage(
            Diagnostic.Kind.ERROR,     
            HELPER.LOCATION(ciet, SF_NAME) +
            "\tThere is a " + k.toString().toLowerCase() + " named " +
            '[' + fcm.getSimpleName().toString() + "] " +
            "which was not declared " + m.toString()
        );

        return true;
    }


    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    // Saving the best for last...
    // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
    //
    // The primary point about this whole annotation, is it (kind-of) helps prevent "Spaghetti
    // Code".  When used, it is intended to mean that a "Class" or "Type" (CIET) **DOES NOT** have
    // any "Global Variables"  (That's really the whole shebang).  If there are declared fields,
    // they must be declared as constants using the 'final' modifier.

    private static boolean fieldIsNotFinalButIsAlsoNotExcused(Element ciet, Element fcm)
    {
        // NOTE: Torello.JDUInternal.Messager **DOES NOT** ALLOW '\t'
        messager.printMessage(
            Diagnostic.Kind.ERROR,     
            HELPER.LOCATION(ciet, SF_NAME) +
            "\tThere is a field named [" + fcm.getSimpleName().toString() + "] " +
            "which was not declared final, nor was it listed excused."
        );

        return true;
    }
}