Class SiteUtil


  • public final class SiteUtil
    extends Object
    Utility class for site generation.
    • Constructor Detail

      • SiteUtil

        private SiteUtil()
        Private utility constructor.
    • Method Detail

      • getMessageKeys

        public static Set<StringgetMessageKeys​(Class<?> module)
                                          throws org.apache.maven.doxia.macro.MacroExecutionException
        Get string values of the message keys from the given check class.
        Parameters:
        module - class to examine.
        Returns:
        a set of checkstyle's module message keys.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if extraction of message keys fails.
      • getCheckMessageKeys

        private static Set<FieldgetCheckMessageKeys​(Class<?> module)
                                               throws org.apache.maven.doxia.macro.MacroExecutionException
        Gets the check's messages keys.
        Parameters:
        module - class to examine.
        Returns:
        a set of checkstyle's module message fields.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the attempt to read a protected class fails.
      • getFieldValue

        public static Object getFieldValue​(Field field,
                                           Object instance)
                                    throws org.apache.maven.doxia.macro.MacroExecutionException
        Returns the value of the given field.
        Parameters:
        field - the field.
        instance - the instance of the module.
        Returns:
        the value of the field.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the value could not be retrieved.
      • getModuleInstance

        public static Object getModuleInstance​(String moduleName)
                                        throws org.apache.maven.doxia.macro.MacroExecutionException
        Returns the instance of the module with the given name.
        Parameters:
        moduleName - the name of the module.
        Returns:
        the instance of the module.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the module could not be created.
      • getPackageObjectFactory

        private static PackageObjectFactory getPackageObjectFactory()
                                                             throws org.apache.maven.doxia.macro.MacroExecutionException
        Returns the default PackageObjectFactory with the default package names.
        Returns:
        the default PackageObjectFactory.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the PackageObjectFactory cannot be created.
      • getNewlineAndIndentSpaces

        public static String getNewlineAndIndentSpaces​(int amountOfSpaces)
        Construct a string with a leading newline character and followed by the given amount of spaces. We use this method only to match indentation in regular xdocs and have minimal diff when parsing the templates. This method exists until 13426
        Parameters:
        amountOfSpaces - the amount of spaces to add after the newline.
        Returns:
        the constructed string.
      • getTemplatePath

        public static Path getTemplatePath​(String moduleName)
                                    throws org.apache.maven.doxia.macro.MacroExecutionException
        Returns path to the template for the given module name or throws an exception if the template cannot be found.
        Parameters:
        moduleName - the module whose template we are looking for.
        Returns:
        path to the template.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the template cannot be found.
      • getXdocsTemplatesFilePaths

        public static Set<PathgetXdocsTemplatesFilePaths()
                                                    throws org.apache.maven.doxia.macro.MacroExecutionException
        Gets xdocs template file paths. These are files ending with .xml.template. This method will be changed to gather .xml once #13426 is resolved.
        Returns:
        a set of xdocs template file paths.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an I/O error occurs.
      • getParentModule

        public static String getParentModule​(Class<?> moduleClass)
                                      throws org.apache.maven.doxia.macro.MacroExecutionException
        Returns the parent module name for the given module class. Returns either "TreeWalker" or "Checker". Returns null if the module class is null.
        Parameters:
        moduleClass - the module class.
        Returns:
        the parent module name as a string.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the parent module cannot be found.
      • getPropertiesForDocumentation

        public static Set<StringgetPropertiesForDocumentation​(Class<?> clss,
                                                                Object instance)
        Get a set of properties for the given class that should be documented.
        Parameters:
        clss - the class to get the properties for.
        instance - the instance of the module.
        Returns:
        a set of properties for the given class.
      • getPropertiesJavadocs

        public static Map<String,​DetailNodegetPropertiesJavadocs​(Set<String> properties,
                                                                         String moduleName,
                                                                         File moduleFile)
                                                                  throws org.apache.maven.doxia.macro.MacroExecutionException
        Get the javadocs of the properties of the module. If the property is not present in the module, then the javadoc of the property from the superclass(es) is used.
        Parameters:
        properties - the properties of the module.
        moduleName - the name of the module.
        moduleFile - the module file.
        Returns:
        the javadocs of the properties of the module.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during processing.
      • assertAllPropertySetterJavadocsAreFound

        private static void assertAllPropertySetterJavadocsAreFound​(Set<String> properties,
                                                                    String moduleName,
                                                                    Map<String,​DetailNode> javadocs)
                                                             throws org.apache.maven.doxia.macro.MacroExecutionException
        Assert that each property has a corresponding setter javadoc that is not null. 'tokens' and 'javadocTokens' are excluded from this check, because their description is different from the description of the setter.
        Parameters:
        properties - the properties of the module.
        moduleName - the name of the module.
        javadocs - the javadocs of the properties of the module.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during processing.
      • processSuperclasses

        private static void processSuperclasses()
                                         throws org.apache.maven.doxia.macro.MacroExecutionException
        Collect the properties setters javadocs of the superclasses.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during processing.
      • processModule

        private static void processModule​(String moduleName,
                                          File moduleFile)
                                   throws org.apache.maven.doxia.macro.MacroExecutionException
        Scrape the Javadocs of the class and its properties setters with ClassAndPropertiesSettersJavadocScraper.
        Parameters:
        moduleName - the name of the module.
        moduleFile - the module file.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during processing.
      • getProperties

        public static Set<StringgetProperties​(Class<?> clss)
        Get a set of properties for the given class.
        Parameters:
        clss - the class to get the properties for.
        Returns:
        a set of properties for the given class.
      • isGlobalProperty

        private static boolean isGlobalProperty​(Class<?> clss,
                                                String propertyName)
        Checks if the property is a global property. Global properties come from the base classes and are common to all checks. For example id, severity, tabWidth, etc.
        Parameters:
        clss - the class of the module.
        propertyName - the name of the property.
        Returns:
        true if the property is a global property.
      • isUndocumentedProperty

        private static boolean isUndocumentedProperty​(Class<?> clss,
                                                      String propertyName)
        Checks if the property is supposed to be documented.
        Parameters:
        clss - the class of the module.
        propertyName - the name of the property.
        Returns:
        true if the property is supposed to be documented.
      • getNonExplicitProperties

        private static Set<StringgetNonExplicitProperties​(Object instance,
                                                            Class<?> clss)
        Gets properties that are not explicitly captured but should be documented if certain conditions are met.
        Parameters:
        instance - the instance of the module.
        clss - the class of the module.
        Returns:
        the non explicit properties.
      • getPropertyDescription

        public static String getPropertyDescription​(String propertyName,
                                                    DetailNode javadoc,
                                                    String moduleName)
                                             throws org.apache.maven.doxia.macro.MacroExecutionException
        Get the description of the property.
        Parameters:
        propertyName - the name of the property.
        javadoc - the Javadoc of the property setter method.
        moduleName - the name of the module.
        Returns:
        the description of the property.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the description could not be extracted.
      • getSinceVersion

        public static String getSinceVersion​(String moduleName,
                                             DetailNode moduleJavadoc,
                                             String propertyName,
                                             DetailNode propertyJavadoc)
                                      throws org.apache.maven.doxia.macro.MacroExecutionException
        Get the since version of the property.
        Parameters:
        moduleName - the name of the module.
        moduleJavadoc - the Javadoc of the module.
        propertyName - the name of the property.
        propertyJavadoc - the Javadoc of the property setter method.
        Returns:
        the since version of the property.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if the since version could not be extracted.
      • getSinceVersionFromJavadoc

        @Nullable
        private static String getSinceVersionFromJavadoc​(DetailNode javadoc)
        Extract the since version from the Javadoc.
        Parameters:
        javadoc - the Javadoc to extract the since version from.
        Returns:
        the since version of the setter.
      • getSinceJavadocTag

        private static DetailNode getSinceJavadocTag​(DetailNode javadoc)
        Find the since Javadoc tag node in the given Javadoc.
        Parameters:
        javadoc - the Javadoc to search.
        Returns:
        the since Javadoc tag node or null if not found.
      • getType

        public static String getType​(Field field,
                                     String propertyName,
                                     String moduleName,
                                     Object instance)
                              throws org.apache.maven.doxia.macro.MacroExecutionException
        Get the type of the property.
        Parameters:
        field - the field to get the type of.
        propertyName - the name of the property.
        moduleName - the name of the module.
        instance - the instance of the module.
        Returns:
        the type of the property.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during getting the type.
      • getDefaultValue

        public static String getDefaultValue​(String propertyName,
                                             Field field,
                                             Object classInstance,
                                             String moduleName)
                                      throws org.apache.maven.doxia.macro.MacroExecutionException
        Get the default value of the property.
        Parameters:
        propertyName - the name of the property.
        field - the field to get the default value of.
        classInstance - the instance of the class to get the default value of.
        moduleName - the name of the module.
        Returns:
        the default value of the property.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during getting the default value.
      • getPatternArrayPropertyValue

        private static String getPatternArrayPropertyValue​(Object fieldValue)
        Gets the name of the bean property's default value for the Pattern array class.
        Parameters:
        fieldValue - The bean property's value
        Returns:
        String form of property's default value
      • removeSquareBrackets

        private static String removeSquareBrackets​(String value)
        Removes square brackets [ and ] from the given string.
        Parameters:
        value - the string to remove square brackets from.
        Returns:
        the string without square brackets.
      • getStringArrayPropertyValue

        private static String getStringArrayPropertyValue​(String propertyName,
                                                          Object value)
        Gets the name of the bean property's default value for the string array class.
        Parameters:
        propertyName - The bean property's name
        value - The bean property's value
        Returns:
        String form of property's default value
      • getValuesStream

        private static Stream<?> getValuesStream​(Object value)
        Generates a stream of values from the given value.
        Parameters:
        value - the value to generate the stream from.
        Returns:
        the stream of values.
      • getIntArrayPropertyValue

        private static String getIntArrayPropertyValue​(Object value)
        Returns the name of the bean property's default value for the int array class.
        Parameters:
        value - The bean property's value.
        Returns:
        String form of property's default value.
      • getIntStream

        private static IntStream getIntStream​(Object value)
        Get the int stream from the given value.
        Parameters:
        value - the value to get the int stream from.
        Returns:
        the int stream.
      • getFieldClass

        private static Class<?> getFieldClass​(Field field,
                                              String propertyName,
                                              String moduleName,
                                              Object instance)
                                       throws org.apache.maven.doxia.macro.MacroExecutionException
        Gets the class of the given field.
        Parameters:
        field - the field to get the class of.
        propertyName - the name of the property.
        moduleName - the name of the module.
        instance - the instance of the module.
        Returns:
        the class of the field.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during getting the class.
      • getPropertyClass

        public static Class<?> getPropertyClass​(String propertyName,
                                                Object instance)
                                         throws org.apache.maven.doxia.macro.MacroExecutionException
        Gets the class of the given java property.
        Parameters:
        propertyName - the name of the property.
        instance - the instance of the module.
        Returns:
        the class of the java property.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if an error occurs during getting the class.
      • getDifference

        public static List<IntegergetDifference​(int[] tokens,
                                                  int... subtractions)
        Get the difference between two lists of tokens.
        Parameters:
        tokens - the list of tokens to remove from.
        subtractions - the tokens to remove.
        Returns:
        the difference between the two lists.
      • getField

        public static Field getField​(Class<?> fieldClass,
                                     String propertyName)
        Gets the field with the given name from the given class.
        Parameters:
        fieldClass - the class to get the field from.
        propertyName - the name of the field.
        Returns:
        the field we are looking for.
      • getLinkToDocument

        public static String getLinkToDocument​(String moduleName,
                                               String document)
                                        throws org.apache.maven.doxia.macro.MacroExecutionException
        Constructs string with relative link to the provided document.
        Parameters:
        moduleName - the name of the module.
        document - the path of the document.
        Returns:
        relative link to the document.
        Throws:
        org.apache.maven.doxia.macro.MacroExecutionException - if link to the document cannot be constructed.