diff --git a/README.md b/README.md index c0c3cfc..6cab7da 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ This is a maven plugin that allows for developers and organizations to ban Maven ## Usage +Here is an example of the primary reason why this plugin is useful. + ```xml ... @@ -42,7 +44,6 @@ This is a maven plugin that allows for developers and organizations to ban Maven .... - https://domain:port/path/file ... @@ -53,18 +54,67 @@ This is a maven plugin that allows for developers and organizations to ban Maven ``` -The `extensions` elements is critical. Without it, the plugin does nothing. With it, the plugin is able to detected ban artifacts before they are downloaded. +The `extensions` elements is critical. Without it, the plugin does nothing for banning artifacts/dependencies. With it, the plugin is able to not only detect ban artifacts, but do it before they are downloaded. This keeps libraries from even reaching your local Maven repository cache. -If no `includes` are provided, then no artifacts will be banned. An *included* artifact is a banned artifact. An *excluded* artifact is not banned. It is the opposite of what you may think. +Here is an example of the non-extension use case for the plugin: -If `groupId` is not provided, it is ignored in the matching process. So it will match all artifact group IDs and the constraint will be for `artifactId` and `version` only. The same is true for `artifactId` and `version`. This means that `` will ban every artifact. +```xml + + ... + + ... + + ... + + com.inteligr8 + ban-maven-plugin + ... + true + + ... + + + + clean + clean + purge-repo + + + + ... + + ... + + ... + +``` -If `groupId` and `groupIdRegex` are both provided, only `groupId` is used. The same is true for `artifactId` and `artifactIdRegex`. The `*Regex` values use standard Java regular expressions. If using regular expressions, remember to escape the dots (`\.`) in group IDs. +The `purge-repo` goal will remove all banned artifacts from your local Maven cache. It does not support `groupIdRegex` or blank `groupId` specifications. So any of those will not be purged/removed. + +## Configuration + +If no `includes` are provided, then no artifacts will be banned. An *included* artifact is a banned artifact. An *excluded* artifact is not banned. It is the opposite of what you may think. If no `excludes` are provided, then no banned artifacts are granted an exception. + +The `artifact` element supports the descriptive `groupId`/`artifactId`/`version` elements or the abbreviated colon-based notation. When using the colon-based notation, the group ID and artifact ID are treated as `groupIdRegex` and `artifactIdRegex` (see below). + +If `groupId` or `artifactId` or `version` are not provided, they are ignored in the matching process. So it will match all applicable artifacts and the constraint will be only for what was specified. This means that `:` will ban every artifact and all their versions. + +If `groupId` and `groupIdRegex` are both provided, only `groupId` is used. The same is true for `artifactId` and `artifactIdRegex`. The `*Regex` element values use standard Java regular expression parsing. If using regular expressions, remember to escape the dots (`\.`) in group IDs. If you do use `groupIdRegex` or use regular expressions in the colon-notation, the matching artifacts will not be purged using the `purge-repo` goal. So if you intend to use that goal, group ID regular expression matching needs be avoided. The `version` element supports the standard Maven specification. You can match a specific version like `1.0.0`. Or you can match all versions before `1.2.17` like `[,1.2.17)`. You can match all future versions after `1.2.17` (inclusive) with `[1.2.17,)`. There is nothing stopping you from specifying two `artifact` elements with the exact same values. So you can ban multiple version ranges of the same artifact by using multiple `artifact` elements. -If you *include* all versions by omitting the `version` element, you can still *exclude* (unban) certain versions, like `[1.2.17,)`. +If you *include* all versions by omitting the `version` element, you can still *exclude* (un-ban) certain versions, like `[1.2.17,)`. -The `import` URL and artifact are to be XML files that conform to the same `configuration` element as described here. In fact, the root elmenet of that XML should be `configuration`. You can create a Maven `pom` packaging type project that deploys the XML to your Maven repository. Importing the configuration allows you to change banned dependencies without making changes to each individual project. Just like with the `include` and `exclude` notation, the `import/artifact` version may be a range. This way the latest banned dependencies can be side-loaded into all projects. This means previously functioning builds may eventually start failing. That is by design in this scenario. +Order does not matter. All include specifications are processed, followed by all exclude specifications. + +## Import + +The `import` URL and artifact are to reference XML files that conform to the same `configuration` element as described here. In fact, the root elmenet of that XML should be `configuration`. It will only support the `includes` and `excludes` elements. so you cannot do recursive imports. + +You can create a Maven `pom` packaging type project that deploys a configuration XML to your Maven repository. Then use an `import` to allow you to change banned dependencies without making changes to each individual project. Just like with the `version` notation in the `includes` and `excludes` elements, your `import` `artifact` element supports a version range. This way the latest banned dependencies can be side-loaded into all projects. This means previously functioning builds may eventually start failing. That is by design in this scenario. + +The `import` elements supports multiple `url` or `artifact` declarations. All imported and directly specified include specifications are processed before all exclude specifications. You cannot change an include when importing, but you can add new ones, that may cover more versions; and you can exclude versions that may have been included by the import. + +The `excludes` element is a way to provide project-by-project exceptions to imported banned artifacts where warranted. diff --git a/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java b/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java index 0d069e4..cd78f74 100644 --- a/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java +++ b/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java @@ -41,7 +41,7 @@ import com.inteligr8.maven.model.ArtifactFilter; public abstract class AbstractBanConfiguration implements BanConfiguration { private final Logger logger = LoggerFactory.getLogger(this.getClass()); - private final Pattern artifactPattern = Pattern.compile("^([^:]+):([^:]+)(:([^:]+))?$"); + private final Pattern artifactPattern = Pattern.compile("^([^:]*):([^:]*)(:([^:]+))?$"); private final Pattern notRegexPattern = Pattern.compile("^[A-Za-z0-9_\\.]*$"); protected final List includeArtifacts = new LinkedList<>();