Class ImportControl


  • class ImportControl
    extends java.lang.Object
    Represents a tree of import rules for controlling whether packages or classes are allowed to be used. Each instance must have a single parent or be the root node. Each instance may have zero or more children.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.List<ImportControl> children
      List of children ImportControl objects.
      private static java.lang.String DOT
      The package separator: "."
      private static java.util.regex.Pattern DOT_PATTERN
      A pattern matching the package separator: "."
      private static java.lang.String DOT_REGEX
      The regex for the package separator: "\\.".
      private java.lang.String fullPackage
      The full package name for the node.
      private ImportControl parent
      The parent.
      private java.util.regex.Pattern patternForExactMatch
      The regex pattern for exact matches - only not null if regex is true.
      private java.util.regex.Pattern patternForPartialMatch
      The regex pattern for partial match (exact and for subpackages) - only not null if regex is true.
      private boolean regex
      If this package represents a regular expression.
      private java.util.Deque<AbstractImportRule> rules
      List of AbstractImportRule objects to check.
      private MismatchStrategy strategyOnMismatch
      Strategy in a case if matching allow/disallow rule was not found.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addImportRule​(AbstractImportRule rule)
      Adds an AbstractImportRule to the node.
      AccessResult checkAccess​(java.lang.String inPkg, java.lang.String forImport)
      Returns whether a package or class is allowed to be imported.
      private static java.util.regex.Pattern createPatternForExactMatch​(java.lang.String expression)
      Creates a Pattern from expression.
      private static java.util.regex.Pattern createPatternForPartialMatch​(java.lang.String expression)
      Creates a Pattern from expression that matches exactly and child packages.
      private static java.lang.String encloseInGroup​(java.lang.String expression)
      Enclose expression in a (non-capturing) group.
      private static java.lang.String ensureSelfContainedRegex​(java.lang.String input, boolean alreadyRegex)
      Returns a regex that is suitable for concatenation by 1) either converting a plain string into a regular expression (handling special characters) or 2) by enclosing input in a (non-capturing) group if input already is a regular expression.
      private AccessResult localCheckAccess​(java.lang.String inPkg, java.lang.String forImport)
      Checks whether any of the rules for this node control access to a specified package or class.
      ImportControl locateFinest​(java.lang.String forPkg)
      Search down the tree to locate the finest match for a supplied package.
      private boolean matchesAtFront​(java.lang.String pkg)
      Matches other package name exactly or partially at front.
      private boolean matchesAtFrontNoRegex​(java.lang.String pkg)
      Non-regex case.
      private boolean matchesExactly​(java.lang.String pkg)
      Check for equality of this with pkg.
      private static java.lang.String toRegex​(java.lang.String input)
      Converts a normal package name into a regex pattern by escaping all special characters that may occur in a java package name.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DOT

        private static final java.lang.String DOT
        The package separator: "."
        See Also:
        Constant Field Values
      • DOT_PATTERN

        private static final java.util.regex.Pattern DOT_PATTERN
        A pattern matching the package separator: "."
      • DOT_REGEX

        private static final java.lang.String DOT_REGEX
        The regex for the package separator: "\\.".
        See Also:
        Constant Field Values
      • parent

        private final ImportControl parent
        The parent. Null indicates we are the root node.
      • fullPackage

        private final java.lang.String fullPackage
        The full package name for the node.
      • patternForPartialMatch

        private final java.util.regex.Pattern patternForPartialMatch
        The regex pattern for partial match (exact and for subpackages) - only not null if regex is true.
      • patternForExactMatch

        private final java.util.regex.Pattern patternForExactMatch
        The regex pattern for exact matches - only not null if regex is true.
      • regex

        private final boolean regex
        If this package represents a regular expression.
      • strategyOnMismatch

        private final MismatchStrategy strategyOnMismatch
        Strategy in a case if matching allow/disallow rule was not found.
    • Constructor Detail

      • ImportControl

        ImportControl​(java.lang.String pkgName,
                      boolean regex,
                      MismatchStrategy strategyOnMismatch)
        Construct a root node.
        Parameters:
        pkgName - the name of the package.
        regex - flags interpretation of pkgName as regex pattern.
        strategyOnMismatch - strategy in a case if matching allow/disallow rule was not found.
      • ImportControl

        ImportControl​(java.lang.String pkgName,
                      boolean regex)
        Construct a root node.
        Parameters:
        pkgName - the name of the package.
        regex - flags interpretation of pkgName as regex pattern.
      • ImportControl

        ImportControl​(ImportControl parent,
                      java.lang.String subPkg,
                      boolean regex,
                      MismatchStrategy strategyOnMismatch)
        Construct a child node. The concatenation of regular expressions needs special care: see ensureSelfContainedRegex(String, boolean) for more details.
        Parameters:
        parent - the parent node.
        subPkg - the sub package name.
        regex - flags interpretation of subPkg as regex pattern.
        strategyOnMismatch - strategy in a case if matching allow/disallow rule was not found.
      • ImportControl

        ImportControl​(ImportControl parent,
                      java.lang.String subPkg,
                      boolean regex)
        Construct a child node. The concatenation of regular expressions needs special care: see ensureSelfContainedRegex(String, boolean) for more details.
        Parameters:
        parent - the parent node.
        subPkg - the sub package name.
        regex - flags interpretation of subPkg as regex pattern.
    • Method Detail

      • ensureSelfContainedRegex

        private static java.lang.String ensureSelfContainedRegex​(java.lang.String input,
                                                                 boolean alreadyRegex)
        Returns a regex that is suitable for concatenation by 1) either converting a plain string into a regular expression (handling special characters) or 2) by enclosing input in a (non-capturing) group if input already is a regular expression.

        1) When concatenating a non-regex package component (like "org.google") with a regex component (like "[^.]+") the other component has to be converted into a regex too, see toRegex(String).

        2) The grouping is strictly necessary if a) input is a regular expression that b) contains the alteration character ('|') and if c) the pattern is not already enclosed in a group - as you see in this example: parent="com|org", child="common|uncommon" will result in the pattern "(?:org|com)\.(?common|uncommon)" what will match "com.common", "com.uncommon", "org.common", and "org.uncommon". Without the grouping it would be "com|org.common|uncommon" which would match "com", "org.common", and "uncommon", which clearly is undesirable. Adding the group fixes this.

        For simplicity the grouping is added to regular expressions unconditionally.

        Parameters:
        input - the input string.
        alreadyRegex - signals if input already is a regular expression.
        Returns:
        a regex string.
      • encloseInGroup

        private static java.lang.String encloseInGroup​(java.lang.String expression)
        Enclose expression in a (non-capturing) group.
        Parameters:
        expression - the input regular expression
        Returns:
        a grouped pattern.
      • toRegex

        private static java.lang.String toRegex​(java.lang.String input)
        Converts a normal package name into a regex pattern by escaping all special characters that may occur in a java package name.
        Parameters:
        input - the input string.
        Returns:
        a regex string.
      • createPatternForPartialMatch

        private static java.util.regex.Pattern createPatternForPartialMatch​(java.lang.String expression)
        Creates a Pattern from expression that matches exactly and child packages.
        Parameters:
        expression - a self-contained regular expression matching the full package exactly.
        Returns:
        a Pattern.
      • createPatternForExactMatch

        private static java.util.regex.Pattern createPatternForExactMatch​(java.lang.String expression)
        Creates a Pattern from expression.
        Parameters:
        expression - a self-contained regular expression matching the full package exactly.
        Returns:
        a Pattern.
      • locateFinest

        public ImportControl locateFinest​(java.lang.String forPkg)
        Search down the tree to locate the finest match for a supplied package.
        Parameters:
        forPkg - the package to search for.
        Returns:
        the finest match, or null if no match at all.
      • matchesAtFront

        private boolean matchesAtFront​(java.lang.String pkg)
        Matches other package name exactly or partially at front.
        Parameters:
        pkg - the package to compare with.
        Returns:
        if it matches.
      • matchesAtFrontNoRegex

        private boolean matchesAtFrontNoRegex​(java.lang.String pkg)
        Non-regex case. Ensure a trailing dot for subpackages, i.e. "com.puppy" will match "com.puppy.crawl" but not "com.puppycrawl.tools".
        Parameters:
        pkg - the package to compare with.
        Returns:
        if it matches.
      • checkAccess

        public AccessResult checkAccess​(java.lang.String inPkg,
                                        java.lang.String forImport)
        Returns whether a package or class is allowed to be imported. The algorithm checks with the current node for a result, and if none is found then calls its parent looking for a match. This will recurse looking for match. If there is no clear result then AccessResult.UNKNOWN is returned.
        Parameters:
        forImport - the import to check on.
        inPkg - the package doing the import.
        Returns:
        an AccessResult.
      • localCheckAccess

        private AccessResult localCheckAccess​(java.lang.String inPkg,
                                              java.lang.String forImport)
        Checks whether any of the rules for this node control access to a specified package or class.
        Parameters:
        forImport - the import to check.
        inPkg - the package doing the import.
        Returns:
        an AccessResult.
      • matchesExactly

        private boolean matchesExactly​(java.lang.String pkg)
        Check for equality of this with pkg.
        Parameters:
        pkg - the package to compare with.
        Returns:
        if it matches.