/*

 *

 * Redistribution and use in source and binary forms, with or without

 * modification, are permitted provided that the following conditions

 * are met:

 *

 *   - Redistributions of source code must retain the above copyright

 *     notice, this list of conditions and the following disclaimer.

 *

 *   - Redistributions in binary form must reproduce the above copyright

 *     notice, this list of conditions and the following disclaimer in the

 *     documentation and/or other materials provided with the distribution.

 *

 *   - Neither the name of Oracle nor the names of its

 *     contributors may be used to endorse or promote products derived

 *     from this software without specific prior written permission.

 *

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,

 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR

 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 */

import java.util.Set;

import java.util.EnumSet;

import javax.annotation.processing.*;

import javax.lang.model.SourceVersion;

import javax.lang.model.element.*;

import javax.lang.model.type.*;

import javax.lang.model.util.*;

import static javax.lang.model.SourceVersion.*;

import static javax.lang.model.element.Modifier.*;

import static javax.lang.model.element.ElementKind.*;

import static javax.lang.model.type.TypeKind.*;

import static javax.lang.model.util.ElementFilter.*;

import static javax.tools.Diagnostic.Kind.*;

/**

 * A sample processor to check naming conventions are being followed.

 *

 * <h3>How to run this processor from the command line</h3>

 * <ol>

 * <li> Compile this file; for example<br>

 *      {@code javac -d procdir CheckNamesProcessor.java}

 * <li> Use {@code javac} to run the annotation processor on itself:<br>

 *      {@code javac -processorpath procdir -processor CheckNamesProcessor -proc:only CheckNamesProcessor.java}

 * </ol>

 *

 * <h3>Another way to run this processor from the command line</h3>

 * <ol>

 * <li> Compile the processor as before

 *

 * <li> Create a UTF-8 encoded text file named {@code

 * javax.annotation.processing.Processor} in the {@code

 * META-INF/services} directory.  The contents of the file are a list

 * of the binary names of the concrete processor classes, one per

 * line.  This provider-configuration file is used by {@linkplain

 * java.util.ServiceLoader service-loader} style lookup.

 *

 * <li> Create a {@code jar} file with the processor classes and

 * {@code META-INF} information.

 *

 * <li> Such a {@code jar} file can now be used with the <i>discovery

 * process</i> without explicitly naming the processor to run:<br>

 * {@code javac -processorpath procdir -proc:only CheckNamesProcessor.java}

 *

 * </ol>

 *

 * <h3>Possible Enhancements</h3>

 * <ul>

 *

 * <li> Support an annotation processor option to control checking

 * exported API elements ({@code public} and {@code protected} ones)

 * or all elements

 *

 * <li> Print out warnings that are more informative

 *

 * <li> Return a true/false status if any warnings were printed or

 * compute and return name warning count

 *

 * <li> Implement checks of package names

 *

 * <li> Use the Tree API, com.sun.source, to examine names within method bodies

 *

 * <li> Define an annotation type whose presence can indicate a

 * different naming convention is being followed

 *

 * <li> Implement customized checks on elements in chosen packages

 *

 * </ul>

 *

 * @author Joseph D. Darcy

 */

@SupportedAnnotationTypes("*")     // Process (check) everything

public class CheckNamesProcessor extends AbstractProcessor {

    private NameChecker nameChecker;

    /**

     * Check that the names of the root elements (and their enclosed

     * elements) follow the appropriate naming conventions.  This

     * processor examines all files regardless of whether or not

     * annotations are present; no new source or class files are

     * generated.

     *

     * <p>Processors that actually process specific annotations should

     * <em>not</em> report supporting {@code *}; this could cause

     * performance degradations and other undesirable outcomes.

     */

    @Override

    public boolean process(Set<? extends TypeElement> annotations,

            RoundEnvironment roundEnv) {

        if (!roundEnv.processingOver()) {

            for (Element element : roundEnv.getRootElements() )

                nameChecker.checkNames(element);

        }

        return false; // Allow other processors to examine files too.

    }

    @Override

    public void init(ProcessingEnvironment processingEnv) {

        super.init(processingEnv);

        nameChecker = new NameChecker(processingEnv);

    }

    @Override

    public SourceVersion getSupportedSourceVersion() {

        /*

         * Return latest source version instead of a fixed version

         *

         * Warnings will be issued if any unknown language constructs

         * are encountered.

         */

        return SourceVersion.latest();

    }

    /**

     * Provide checks that an element and its enclosed elements follow

     * the usual naming conventions.

     *

     * <p> Conventions from section 6.8 of

     *     <cite>The Java&trade; Language Specification</cite>

     *

     * <ul>

     * <li> Classes and interfaces: camel case, first letter is uppercase

     * <li> Methods: camel case, first letter is lowercase

     * <li> Type variables: one uppercase letter

     * <li> Fields

     * <ul>

     * <li> non-final: camel case, initial lowercase

     * <li> constant: uppercase separated by underscores

     * </ul>

     * <li> Packages: checks left as exercise for the reader, see section 7.7 of

     * <cite>The Java&trade; Language Specification</cite>.

     * </ul>

     */

    private static class NameChecker {

        private final Messager messager;

        private final Types typeUtils;

        NameCheckScanner nameCheckScanner = new NameCheckScanner();

        NameChecker(ProcessingEnvironment processsingEnv) {

            this.messager  = processsingEnv.getMessager();

            this.typeUtils = processsingEnv.getTypeUtils();

        }

        /**

         * If the name of the argument or its enclosed elements

         * violates the naming conventions, report a warning.

         */

        public void checkNames(Element element) {

            // Implement name checks with a visitor, but expose that

            // functionality through this method instead.

            nameCheckScanner.scan(element);

        }

        /**

         * Visitor to implement name checks.

         */

        private class NameCheckScanner extends ElementScanner9<Void, Void> {

            // The visitor could be enhanced to return true/false if

            // there were warnings reported or a count of the number

            // of warnings.  This could be facilitated by using

            // Boolean or Integer instead of Void for the actual type

            // arguments.  In more detail, one way to tally the number

            // of warnings would be for each method to return the sum

            // of the warnings it and the methods it called issued, a

            // bottom-up computation.  In that case, the first type

            // argument would be Integer and the second type argument

            // would still be Void.  Alternatively, the current count

            // could be passed along in Integer parameter p and each

            // method could return the Integer sum of p and the

            // warnings the method issued.  Some computations are more

            // naturally expressed in one form instead of the other.

            // If greater control is needed over traversal order, a

            // SimpleElementVisitor can be extended instead of an

            // ElementScanner.

            /**

             * Check the name of a type and its enclosed elements and

             * type parameters.

             */

            @Override

            public Void visitType(TypeElement e, Void p) {

                scan(e.getTypeParameters(), p); // Check the names of any type parameters

                checkCamelCase(e, true);        // Check the name of the class or interface

                super.visitType(e, p);          // Check the names of any enclosed elements

                return null;

            }

            /**

             * Check the name of an executable (method, constructor,

             * etc.) and its type parameters.

             */

            @Override

            public Void visitExecutable(ExecutableElement e, Void p) {

                scan(e.getTypeParameters(), p); // Check the names of any type parameters

                // Check the name of the executable

                if (e.getKind() == METHOD) {

                    // Make sure that a method does not have the same

                    // name as its class or interface.

                    Name name = e.getSimpleName();

                    if (name.contentEquals(e.getEnclosingElement().getSimpleName()))

                        messager.printMessage(WARNING,

                                              "A method should not have the same name as its enclosing type, ``" +

                                              name + "''." , e);

                    checkCamelCase(e, false);

                }

                // else constructors and initializers don't have user-defined names

                // At this point, could use the Tree API,

                // com.sun.source, to examine the names of entities

                // inside a method.

                super.visitExecutable(e, p);

                return null;

            }

            /**

             * Check the name of a field, parameter, etc.

             */

            @Override

            public Void visitVariable(VariableElement e, Void p) {

                if (!checkForSerial(e)) { // serialVersionUID checks

                    // Is the variable a constant?

                    if (e.getKind() == ENUM_CONSTANT ||

                        e.getConstantValue() != null ||

                        heuristicallyConstant(e) )

                        checkAllCaps(e); // includes enum constants

                    else

                        checkCamelCase(e, false);

                }

                // A call to super can be elided with the current language definition.

                // super.visitVariable(e, p);

                return null;

            }

            /**

             * Check the name of a type parameter.

             */

            @Override

            public Void visitTypeParameter(TypeParameterElement e, Void p) {

                checkAllCaps(e);

                // A call to super can be elided with the current language definition.

                // super.visitTypeParameter(e, p);

                return null;

            }

            /**

             * Check the name of a package.

             */

            @Override

            public Void visitPackage(PackageElement e, Void p) {

                /*

                 * Implementing the checks of package names is left

                 * as an exercise for the reader, see JLS section

                 * 7.7 for conventions.

                 */

                // Whether or not this method should call

                // super.visitPackage, to visit the packages enclosed

                // elements, is a design decision based on what a

                // PackageElemement is used to mean in this context.

                // A PackageElement can represent a whole package, so

                // it can provide a concise way to indicate many

                // user-defined types should be visited.  However, a

                // PackageElement can also represent a

                // package-info.java file, as would be in the case if

                // the PackageElement came from

                // RoundEnvironment.getRootElements.  In that case,

                // the package-info file and other files in that

                // package could be passed in.  Therefore, without

                // further checks, types in a package could be visited

                // more than once if a package's elements were visited

                // too.

                return null;

            }

            @Override

            public Void visitUnknown(Element e, Void p) {

                // This method will be called if a kind of element

                // writing the conventions for such constructs aren't

                // known, issue a warning.

                messager.printMessage(WARNING,

                                      "Unknown kind of element, " + e.getKind() +

                                      ", no name checking performed.", e);

                return null;

            }

            // All the name checking methods assume the examined names

            // are syntactically well-formed identifiers.

            /**

             * Return {@code true} if this variable is a field named

             * "serialVersionUID"; false otherwise.  A true

             * serialVersionUID of a class has type {@code long} and

             * is static and final.

             *

             * <p>To check that a Serializable class defines a proper

             * serialVersionUID, run javac with -Xlint:serial.

             *

             * @return true if this variable is a serialVersionUID field and false otherwise

             */

            private boolean checkForSerial(VariableElement e) {

                // If a field is named "serialVersionUID" ...

                if (e.getKind() == FIELD &&

                    e.getSimpleName().contentEquals("serialVersionUID")) {

                    // ... issue a warning if it does not act as a serialVersionUID

                    if (!(e.getModifiers().containsAll(EnumSet.of(STATIC, FINAL)) &&

                            typeUtils.isSameType(e.asType(), typeUtils.getPrimitiveType(LONG)) &&

                            e.getEnclosingElement().getKind() == CLASS )) // could check that class implements Serializable

                        messager.printMessage(WARNING,

                                              "Field named ``serialVersionUID'' is not acting as such.", e);

                    return true;

                }

                return false;

            }

            /**

             * Using heuristics, return {@code true} is the variable

             * should follow the naming conventions for constants and

             * {@code false} otherwise.  For example, the public

             * static final fields ZERO, ONE, and TEN in

             * java.math.BigDecimal are logically constants (and named

             * as constants) even though BigDecimal values are not

             * regarded as constants by the language specification.

             * However, some final fields may not act as constants

             * since the field may be a reference to a mutable object.

             *

             * <p> These heuristics could be tweaked to provide better

             * fidelity.

             *

             * @return true if the current heuristics regard the

             * variable as a constant and false otherwise.

             */

            private boolean heuristicallyConstant(VariableElement e) {

                // Fields declared in interfaces are logically

                // constants, JLSv3 section 9.3.

                if (e.getEnclosingElement().getKind() == INTERFACE)

                    return true;

                else if (e.getKind() == FIELD &&

                         e.getModifiers().containsAll(EnumSet.of(PUBLIC, STATIC, FINAL)))

                    return true;

                else {

                    // A parameter declared final should not be named like

                    // a constant, neither should exception parameters.

                    return false;

                }

            }

            /**

             * Print a warning if an element's simple name is not in

             * camel case.  If there are two adjacent uppercase

             * characters, the name is considered to violate the

             * camel case naming convention.

             *

             * @param e the element whose name will be checked

             * @param initialCaps whether or not the first character should be uppercase

             */

            private void checkCamelCase(Element e, boolean initialCaps) {

                String name = e.getSimpleName().toString();

                boolean previousUpper = false;

                boolean conventional = true;

                int firstCodePoint = name.codePointAt(0);

                if (Character.isUpperCase(firstCodePoint)) {

                    previousUpper = true;

                    if (!initialCaps) {

                        messager.printMessage(WARNING,

                        return;

                    }

                } else if (Character.isLowerCase(firstCodePoint)) {

                    if (initialCaps) {

                        messager.printMessage(WARNING,

                        return;

                    }

                } else // underscore, etc.

                    conventional = false;

                if (conventional) {

                    int cp = firstCodePoint;

                    for (int i = Character.charCount(cp);

                         i < name.length();

                         i += Character.charCount(cp)) {

                        cp = name.codePointAt(i);

                        if (Character.isUpperCase(cp)){

                            if (previousUpper) {

                                conventional = false;

                                break;

                            }

                            previousUpper = true;

                        } else

                            previousUpper = false;

                    }

                }

                if (!conventional)

                    messager.printMessage(WARNING,

            }

            /**

             * Print a warning if the element's name is not a sequence

             * of uppercase letters separated by underscores ("_").

             *

             * @param e the element whose name will be checked

             */

            private void checkAllCaps(Element e) {

                String name = e.getSimpleName().toString();

                    if (name.codePointCount(0, name.length()) > 1 ||

                        // Assume names are non-empty

                        !Character.isUpperCase(name.codePointAt(0)))

                        messager.printMessage(WARNING,

                                              "A type variable's name,``" + name +

                                              "'', should be a single uppercace character.",

                                              e);

                } else {

                    boolean conventional = true;

                    int firstCodePoint = name.codePointAt(0);

                    // Starting with an underscore is not conventional

                    if (!Character.isUpperCase(firstCodePoint))

                        conventional = false;

                    else {

                        // Was the previous character an underscore?

                        boolean previousUnderscore = false;

                        int cp = firstCodePoint;

                        for (int i = Character.charCount(cp);

                             i < name.length();

                             i += Character.charCount(cp)) {

                            cp = name.codePointAt(i);

                            if (cp == (int) '_') {

                                if (previousUnderscore) {

                                    conventional = false;

                                    break;

                                }

                                previousUnderscore = true;

                            } else {

                                previousUnderscore = false;

                                if (!Character.isUpperCase(cp) && !Character.isDigit(cp) ) {

                                    conventional = false;

                                    break;

                                }

                            }

                        }

                    }

                    if (!conventional)

                        messager.printMessage(WARNING,

                                              "A constant's name, ``" + name + "'', should be ALL_CAPS.",

                                              e);

                }

            }

        }

    }

}

/**

 * Lots of bad names.  Don't write code like this!

 */

class BADLY_NAMED_CODE {