From bef065e9641767635f5cba115813b653085136bd Mon Sep 17 00:00:00 2001 From: "Brian M. Long" Date: Wed, 9 Jul 2025 10:05:28 -0400 Subject: [PATCH] docs and tidy up --- pom.xml | 31 ++++++++----- .../maven/ban/AbstractBanConfiguration.java | 31 +++++++++++++ .../maven/ban/BanConfigurationDownloader.java | 44 ++++++++++++++++++- .../maven/ban/BanDependencyFilter.java | 12 +++++ .../com/inteligr8/maven/ban/BanExtension.java | 6 ++- ...java => BanPluginConfigurationParser.java} | 9 +++- .../inteligr8/maven/ban/PurgeRepoMojo.java | 6 +-- 7 files changed, 118 insertions(+), 21 deletions(-) rename src/main/java/com/inteligr8/maven/ban/{BanConfigurationParser.java => BanPluginConfigurationParser.java} (71%) diff --git a/pom.xml b/pom.xml index f586d07..c775939 100644 --- a/pom.xml +++ b/pom.xml @@ -88,9 +88,9 @@ test - junit - junit - 4.13.2 + org.junit.jupiter + junit-jupiter-api + 5.12.0 test @@ -106,6 +106,16 @@ maven-invoker-plugin 3.9.0 + + org.eclipse.sisu + sisu-maven-plugin + 0.9.0.M2 + + + org.codehaus.plexus + plexus-component-metadata + 2.2.0 + @@ -132,7 +142,6 @@ org.eclipse.sisu sisu-maven-plugin - 0.3.5 generate-index @@ -145,7 +154,6 @@ org.codehaus.plexus plexus-component-metadata - 2.2.0 @@ -210,7 +218,7 @@ - ossrh-release + central-publish @@ -247,14 +255,13 @@ - org.sonatype.plugins - nexus-staging-maven-plugin - 1.7.0 + org.sonatype.central + central-publishing-maven-plugin + 0.8.0 true - ossrh - https://s01.oss.sonatype.org/ - true + central + true diff --git a/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java b/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java index 076740e..b55f466 100644 --- a/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java +++ b/src/main/java/com/inteligr8/maven/ban/AbstractBanConfiguration.java @@ -43,6 +43,37 @@ import org.slf4j.LoggerFactory; import com.inteligr8.maven.model.ArtifactFilter; +/** + * This class handles the parsing of the configuration specification supported + * by this plugin. It does not implement the banning execution; just the + * collection of configurations to decide what artifacts should be banned. + * + * The specification is as follows: + * + * ```xml + * + * + * relative/path/file.xml + * https://host.domain/path/file.xml + * domain.host:artifact-id:[1.0,) + * + * + * log4j:log4j + * org.apache.logging:log4j-impl:[,2.16.1) + * + * + * ... + * + * + * ``` + * + * The imports are recursively processed under the same specification. The + * included artifacts are the ones that are banned. Any artifact matching both + * includes and excludes will be excluded and therefore NOT banned. + * + * The `groupId` and `artifactId` of the standard shorthand Maven `artifact` + * nomenclature may use regular expressions. + */ public abstract class AbstractBanConfiguration implements BanConfiguration { private final Logger logger = LoggerFactory.getLogger(this.getClass()); diff --git a/src/main/java/com/inteligr8/maven/ban/BanConfigurationDownloader.java b/src/main/java/com/inteligr8/maven/ban/BanConfigurationDownloader.java index ff55ce3..bb5a540 100644 --- a/src/main/java/com/inteligr8/maven/ban/BanConfigurationDownloader.java +++ b/src/main/java/com/inteligr8/maven/ban/BanConfigurationDownloader.java @@ -31,10 +31,24 @@ import org.eclipse.aether.impl.VersionRangeResolver; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +/** + * This class parses the a configuration file that conforms with the + * specification defined by this plugin. + */ public class BanConfigurationDownloader extends AbstractBanConfiguration { private final Logger logger = LoggerFactory.getLogger(this.getClass()); + /** + * This constructs the downloader based on an accessible URL. + * + * @param session A Maven session object. + * @param artifactResolver A Maven Aether artifact resolver service. + * @param versionRangeResolver A Maven Aether version range resolver service. + * @param url The URL of a ban configuration file. + * @throws IOException The file could not be downloaded for any number of reasons. + * @throws MojoFailureException The file could not be parsed due to bad formatting or unexpected response. + */ public BanConfigurationDownloader(MavenSession session, ArtifactResolver artifactResolver, VersionRangeResolver versionRangeResolver, String url) throws IOException, MojoFailureException { super(session, artifactResolver, versionRangeResolver); @@ -45,7 +59,17 @@ public class BanConfigurationDownloader extends AbstractBanConfiguration { throw new MojoFailureException(xppe.getMessage(), xppe); } } - + + /** + * This constructs the downloader based on a file object. + * + * @param session A Maven session object. + * @param artifactResolver A Maven Aether artifact resolver service. + * @param versionRangeResolver A Maven Aether version range resolver service. + * @param file A file, typically local, though technically may be remote. + * @throws IOException The file could not be read for any number of reasons. + * @throws MojoFailureException The file could not be parsed due to bad formatting. + */ public BanConfigurationDownloader(MavenSession session, ArtifactResolver artifactResolver, VersionRangeResolver versionRangeResolver, File file) throws IOException, MojoFailureException { super(session, artifactResolver, versionRangeResolver); @@ -57,6 +81,14 @@ public class BanConfigurationDownloader extends AbstractBanConfiguration { } } + /** + * This method loads the configuration from the specified URL. + * + * @param url A URL of a ban configuration file. + * @return A Maven Plexus XML DOM object. + * @throws IOException The file could not be downloaded for any number of reasons. + * @throws MojoFailureException The file could not be parsed due to bad formatting or unexpected response. + */ private Xpp3Dom load(URL url) throws IOException, XmlPullParserException { InputStream istream = url.openStream(); BufferedInputStream bistream = new BufferedInputStream(istream, 16384); @@ -67,7 +99,15 @@ public class BanConfigurationDownloader extends AbstractBanConfiguration { bistream.close(); } } - + + /** + * This method loads the configuration from the specified file. + * + * @param file A file, typically local, though technically may be remote. + * @return A Maven Plexus XML DOM object. + * @throws IOException The file could not be read for any number of reasons. + * @throws MojoFailureException The file could not be parsed due to bad formatting. + */ private Xpp3Dom load(File file) throws IOException, XmlPullParserException { FileInputStream fistream = new FileInputStream(file); BufferedInputStream bistream = new BufferedInputStream(fistream, 16384); diff --git a/src/main/java/com/inteligr8/maven/ban/BanDependencyFilter.java b/src/main/java/com/inteligr8/maven/ban/BanDependencyFilter.java index 883958d..3818ef0 100644 --- a/src/main/java/com/inteligr8/maven/ban/BanDependencyFilter.java +++ b/src/main/java/com/inteligr8/maven/ban/BanDependencyFilter.java @@ -28,6 +28,18 @@ import org.slf4j.LoggerFactory; import com.inteligr8.maven.model.ArtifactFilter; +/** + * This class implements the banned artifact detection logic. + * + * It will recursively scan every dependency and plugin dependency to find any + * artifacts that reference a banned artifact and its banned versions. If one + * is found, the filter will fail and stop the build immediately. It will + * prevent the banned artifact from being downloaded. + * + * The complicated part is that when multiple versions of the same artifact + * show up in the dependency tree, only one may be selected. So this filter + * will ignore the versions that are not selected. + */ public class BanDependencyFilter implements DependencyFilter { private final Logger logger = LoggerFactory.getLogger(this.getClass()); diff --git a/src/main/java/com/inteligr8/maven/ban/BanExtension.java b/src/main/java/com/inteligr8/maven/ban/BanExtension.java index 881f172..32dbed3 100644 --- a/src/main/java/com/inteligr8/maven/ban/BanExtension.java +++ b/src/main/java/com/inteligr8/maven/ban/BanExtension.java @@ -87,7 +87,9 @@ public class BanExtension extends AbstractMavenLifecycleParticipant { if (config == null) return; - BanDependencyFilter depFilter = new BanDependencyFilter(config.getIncludeArtifacts(), config.getExcludeArtifacts()); + BanDependencyFilter depFilter = new BanDependencyFilter( + config.getIncludeArtifacts(), + config.getExcludeArtifacts()); depFilter.setFailFast(true); MavenProject project = session.getCurrentProject(); @@ -132,7 +134,7 @@ public class BanExtension extends AbstractMavenLifecycleParticipant { return null; } else { try { - return new BanConfigurationParser(session, this.artifactResolver, this.versionRangeResolver, plugin); + return new BanPluginConfigurationParser(session, this.artifactResolver, this.versionRangeResolver, plugin); } catch (IOException | MojoFailureException e) { throw new MavenExecutionException(e.getMessage(), project.getFile()); } diff --git a/src/main/java/com/inteligr8/maven/ban/BanConfigurationParser.java b/src/main/java/com/inteligr8/maven/ban/BanPluginConfigurationParser.java similarity index 71% rename from src/main/java/com/inteligr8/maven/ban/BanConfigurationParser.java rename to src/main/java/com/inteligr8/maven/ban/BanPluginConfigurationParser.java index a9646df..9ad9928 100644 --- a/src/main/java/com/inteligr8/maven/ban/BanConfigurationParser.java +++ b/src/main/java/com/inteligr8/maven/ban/BanPluginConfigurationParser.java @@ -23,9 +23,14 @@ import org.codehaus.plexus.util.xml.Xpp3Dom; import org.eclipse.aether.impl.ArtifactResolver; import org.eclipse.aether.impl.VersionRangeResolver; -public class BanConfigurationParser extends AbstractBanConfiguration { +/** + * This class parses the POM plugin configuration block for this plugin. The + * specification for that configuration block is shared with the one found in + * the ban configuration file. + */ +public class BanPluginConfigurationParser extends AbstractBanConfiguration { - public BanConfigurationParser(MavenSession session, ArtifactResolver artifactResolver, VersionRangeResolver versionRangeResolver, Plugin plugin) throws IOException, MojoFailureException { + public BanPluginConfigurationParser(MavenSession session, ArtifactResolver artifactResolver, VersionRangeResolver versionRangeResolver, Plugin plugin) throws IOException, MojoFailureException { super(session, artifactResolver, versionRangeResolver); Xpp3Dom rootDom = (Xpp3Dom) plugin.getConfiguration(); diff --git a/src/main/java/com/inteligr8/maven/ban/PurgeRepoMojo.java b/src/main/java/com/inteligr8/maven/ban/PurgeRepoMojo.java index 8def91d..0cd5973 100644 --- a/src/main/java/com/inteligr8/maven/ban/PurgeRepoMojo.java +++ b/src/main/java/com/inteligr8/maven/ban/PurgeRepoMojo.java @@ -88,7 +88,7 @@ public class PurgeRepoMojo extends AbstractMojo { private void purge() throws MojoFailureException, IOException { List includePaths = new LinkedList<>(); - BanConfigurationParser config = this.getConfiguration(); + BanPluginConfigurationParser config = this.getConfiguration(); for (ArtifactFilter afilter : config.getIncludeArtifacts()) { if (afilter.getGroupId() == null) { @@ -172,12 +172,12 @@ public class PurgeRepoMojo extends AbstractMojo { } } - private BanConfigurationParser getConfiguration() throws MojoFailureException, IOException { + private BanPluginConfigurationParser getConfiguration() throws MojoFailureException, IOException { MavenProject project = this.session.getCurrentProject(); Plugin plugin = project.getPlugin(BanExtension.THIS_PLUGIN_KEY); if (plugin == null) throw new MojoFailureException("The plugin is executing but it cannot be found"); - return new BanConfigurationParser(this.session, this.artifactResolver, this.versionRangeResolver, plugin); + return new BanPluginConfigurationParser(this.session, this.artifactResolver, this.versionRangeResolver, plugin); } private Path resolveGroupPath(ArtifactFilter afilter) {