From ff746d08621b63bbb580f84ee335ad3365281f06 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Tue, 26 Jan 2021 09:37:55 -0800 Subject: [PATCH 1/2] [MJAVADOC-329] - Allow generation of empty javadoc JARs Add generateIfEmpty (default false) to javadoc:jar goal Add testGenerateIfEmpty (default false) to javadoc:test-jar goal --- .../plugins/javadoc/AbstractJavadocMojo.java | 50 +++++++++++++------ .../maven/plugins/javadoc/JavadocJar.java | 15 ++++++ .../maven/plugins/javadoc/TestJavadocJar.java | 14 ++++++ 3 files changed, 63 insertions(+), 16 deletions(-) diff --git a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java index 10e316800..439d2497c 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java @@ -1999,7 +1999,30 @@ protected void executeReport( Locale unusedLocale ) Collection collectedSourcePaths = collect( sourcePaths.values() ); Map> files = getFiles( collectedSourcePaths ); - if ( !canGenerateReport( files ) ) + + boolean canGenerateReport = canGenerateReport( files ); + + if ( !canGenerateReport && !canGenerateIfEmpty() ) + { + return; + } + + // ---------------------------------------------------------------------- + // Javadoc output directory as File + // ---------------------------------------------------------------------- + + File javadocOutputDirectory = new File( getOutputDirectory() ); + if ( javadocOutputDirectory.exists() && !javadocOutputDirectory.isDirectory() ) + { + throw new MavenReportException( "IOException: " + getOutputDirectory() + " is not a directory." ); + } + if ( javadocOutputDirectory.exists() && !javadocOutputDirectory.canWrite() ) + { + throw new MavenReportException( "IOException: " + getOutputDirectory() + " is not writable." ); + } + javadocOutputDirectory.mkdirs(); + + if ( !canGenerateReport ) { return; } @@ -2029,21 +2052,6 @@ protected void executeReport( Locale unusedLocale ) packageNames = getPackageNames( files ); } - // ---------------------------------------------------------------------- - // Javadoc output directory as File - // ---------------------------------------------------------------------- - - File javadocOutputDirectory = new File( getOutputDirectory() ); - if ( javadocOutputDirectory.exists() && !javadocOutputDirectory.isDirectory() ) - { - throw new MavenReportException( "IOException: " + getOutputDirectory() + " is not a directory." ); - } - if ( javadocOutputDirectory.exists() && !javadocOutputDirectory.canWrite() ) - { - throw new MavenReportException( "IOException: " + getOutputDirectory() + " is not writable." ); - } - javadocOutputDirectory.mkdirs(); - // ---------------------------------------------------------------------- // Copy all resources // ---------------------------------------------------------------------- @@ -2225,6 +2233,16 @@ protected void executeReport( Locale unusedLocale ) } } + /** + * Determine if an empty jar can be generated. + * + * @return true if an empty jar can be generated, otherwise false + */ + protected boolean canGenerateIfEmpty() + { + return false; + } + protected final Collection collect( Collection> sourcePaths ) { Collection collectedSourcePaths = new LinkedHashSet<>(); diff --git a/src/main/java/org/apache/maven/plugins/javadoc/JavadocJar.java b/src/main/java/org/apache/maven/plugins/javadoc/JavadocJar.java index d923983b0..c2e102edb 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/JavadocJar.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/JavadocJar.java @@ -167,6 +167,14 @@ public class JavadocJar @Parameter( defaultValue = "${project.build.outputTimestamp}" ) private String outputTimestamp; + /** + * Generate Javadoc archive even if empty. + * + * @since 3.2.1 + */ + @Parameter( defaultValue = "false" ) + private boolean generateIfEmpty; + /** {@inheritDoc} */ @Override public void doExecute() @@ -251,6 +259,13 @@ protected String getClassifier() return classifier; } + /** {@inheritDoc} */ + @Override + protected boolean canGenerateIfEmpty() + { + return generateIfEmpty; + } + // ---------------------------------------------------------------------- // private methods // ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocJar.java b/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocJar.java index e78b8865c..c2d882877 100644 --- a/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocJar.java +++ b/src/main/java/org/apache/maven/plugins/javadoc/TestJavadocJar.java @@ -115,6 +115,14 @@ public class TestJavadocJar @Parameter( property = "maven.javadoc.testClassifier", defaultValue = "test-javadoc", required = true ) private String testClassifier; + /** + * Generate Test Javadoc archive even if empty. + * + * @since 3.2.1 + */ + @Parameter( defaultValue = "false" ) + private boolean testGenerateIfEmpty; + // ---------------------------------------------------------------------- // Protected methods // ---------------------------------------------------------------------- @@ -159,6 +167,12 @@ protected String getWindowtitle() return testWindowtitle; } + @Override + protected boolean canGenerateIfEmpty() + { + return testGenerateIfEmpty; + } + @Override protected List getProjectBuildOutputDirs( MavenProject p ) { From 5709d4da6264d84a476f77399a95cced52539145 Mon Sep 17 00:00:00 2001 From: John Fallows Date: Tue, 26 Jan 2021 09:41:04 -0800 Subject: [PATCH 2/2] [MJAVADOC-329] - Allow generation of empty javadoc JARs Add unit test for javadoc:jar generateIfEmpty --- .../maven/plugins/javadoc/JavadocJarTest.java | 13 +++ ...docJarGenerateIfEmptyMavenProjectStub.java | 90 +++++++++++++++++++ ...vadocjar-generateifempty-plugin-config.xml | 83 +++++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 src/test/java/org/apache/maven/plugins/javadoc/stubs/JavadocJarGenerateIfEmptyMavenProjectStub.java create mode 100644 src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml diff --git a/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarTest.java b/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarTest.java index 900851cb1..f0c3e1603 100644 --- a/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarTest.java +++ b/src/test/java/org/apache/maven/plugins/javadoc/JavadocJarTest.java @@ -204,4 +204,17 @@ public void testIncludeMavenDescriptorWhenExplicitlyConfigured() throws Exceptio assertTrue("Expected jar to contain " + entry, set.contains(entry)); } } + + public void testGenerateIfEmpty() throws Exception + { + File testPom = + new File( getBasedir(), "src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml" ); + JavadocJar mojo = lookupMojo( testPom ); + mojo.execute(); + + //check if the javadoc jar file was generated + File generatedFile = + new File( getBasedir(), "target/test/unit/javadocjar-generateifempty/target/javadocjar-generateifempty-javadoc.jar" ); + assertTrue( FileUtils.fileExists( generatedFile.getAbsolutePath() ) ); + } } diff --git a/src/test/java/org/apache/maven/plugins/javadoc/stubs/JavadocJarGenerateIfEmptyMavenProjectStub.java b/src/test/java/org/apache/maven/plugins/javadoc/stubs/JavadocJarGenerateIfEmptyMavenProjectStub.java new file mode 100644 index 000000000..bdc9429a4 --- /dev/null +++ b/src/test/java/org/apache/maven/plugins/javadoc/stubs/JavadocJarGenerateIfEmptyMavenProjectStub.java @@ -0,0 +1,90 @@ +package org.apache.maven.plugins.javadoc.stubs; + +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import org.apache.maven.model.Build; +import org.apache.maven.model.Scm; +import org.apache.maven.plugin.testing.stubs.MavenProjectStub; + +import java.io.File; +import java.util.ArrayList; +import java.util.List; + +/** + * @author John Fallows + */ +public class JavadocJarGenerateIfEmptyMavenProjectStub + extends MavenProjectStub +{ + private Scm scm; + + public JavadocJarGenerateIfEmptyMavenProjectStub() + { + readModel( new File( getBasedir(), "javadocjar-generateifempty-plugin-config.xml" ) ); + + setGroupId( getModel().getGroupId() ); + setArtifactId( getModel().getArtifactId() ); + setVersion( getModel().getVersion() ); + setName( getModel().getName() ); + setUrl( getModel().getUrl() ); + setPackaging( getModel().getPackaging() ); + + Scm scm = new Scm(); + scm.setConnection( "scm:svn:http://svn.apache.org/maven/sample/trunk" ); + setScm( scm ); + + JavadocPluginArtifactStub artifact = + new JavadocPluginArtifactStub( getGroupId(), getArtifactId(), getVersion(), getPackaging() ); + artifact.setArtifactHandler( new DefaultArtifactHandlerStub() ); + artifact.setType( "jar" ); + artifact.setBaseVersion( "1.0-SNAPSHOT" ); + setArtifact( artifact ); + + Build build = new Build(); + build.setFinalName( "javadocjar-generateifempty" ); + build.setDirectory( super.getBasedir() + "/target/test/unit/javadocjar-generateifempty/target" ); + setBuild( build ); + + List compileSourceRoots = new ArrayList<>(); + compileSourceRoots.add( getBasedir().getAbsolutePath() ); + setCompileSourceRoots( compileSourceRoots ); + } + + /** {@inheritDoc} */ + @Override + public Scm getScm() + { + return scm; + } + + /** {@inheritDoc} */ + @Override + public void setScm( Scm scm ) + { + this.scm = scm; + } + + /** {@inheritDoc} */ + @Override + public File getBasedir() + { + return new File( super.getBasedir() + "/src/test/resources/unit/javadocjar-generateifempty" ); + } +} diff --git a/src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml b/src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml new file mode 100644 index 000000000..64979a8e8 --- /dev/null +++ b/src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml @@ -0,0 +1,83 @@ + + + + 4.0.0 + org.apache.maven.plugins.maven-javadoc-plugin.unit + javadocjar-generateifempty + jar + 1.0-SNAPSHOT + 2006 + Maven Javadoc Plugin Javadoc Jar Default Config Test + http://maven.apache.org + + + + org.apache.maven.plugins + maven-javadoc-plugin + + + ${localRepository} + ${basedir}/target/test/unit/javadocjar-generateifempty/target + ${basedir}/target/test/unit/javadocjar-generateifempty/target/site/apidocs + javadocjar-generateifempty + true + javadoc + false + false + protected + true + false + true + ISO-8859-1 + false + false + false + false + false + false + false + false + false + false + false + false + java + + doc,title + bottom,comma test +
my footer, and something
+
my header, and something else
+ Maven Javadoc Plugin, Javadoc Jar Default Config Test 1.0-SNAPSHOT API + + + true + true + true + false + true + + + + + + + +