[MJAVADOC-329] Allow generation of empty javadoc JARs

src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java

@@ -1999,7 +1999,30 @@ protected void executeReport( Locale unusedLocale )
         Collection<Path> collectedSourcePaths = collect( sourcePaths.values() );
 
         Map<Path, Collection<String>> 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 <T> Collection<T> collect( Collection<Collection<T>> sourcePaths )
     {
         Collection<T> collectedSourcePaths = new LinkedHashSet<>();

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
     // ----------------------------------------------------------------------

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<File> getProjectBuildOutputDirs( MavenProject p )
     {

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() ) );
+    }
 }

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 <a href="mailto:jfallows@apache.org">John Fallows</a>
+ */
+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<String> 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" );
+    }
+}

src/test/resources/unit/javadocjar-generateifempty/javadocjar-generateifempty-plugin-config.xml

@@ -0,0 +1,83 @@
+<!--
+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.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>org.apache.maven.plugins.maven-javadoc-plugin.unit</groupId>
+  <artifactId>javadocjar-generateifempty</artifactId>
+  <packaging>jar</packaging>
+  <version>1.0-SNAPSHOT</version>
+  <inceptionYear>2006</inceptionYear>
+  <name>Maven Javadoc Plugin Javadoc Jar Default Config Test</name>
+  <url>http://maven.apache.org</url>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <project implementation="org.apache.maven.plugins.javadoc.stubs.JavadocJarFailOnErrorMavenProjectStub"/>
+          <localRepository>${localRepository}</localRepository>
+          <jarOutputDirectory>${basedir}/target/test/unit/javadocjar-generateifempty/target</jarOutputDirectory>
+          <outputDirectory>${basedir}/target/test/unit/javadocjar-generateifempty/target/site/apidocs</outputDirectory>
+          <finalName>javadocjar-generateifempty</finalName>
+          <attach>true</attach>
+          <classifier>javadoc</classifier>
+          <breakiterator>false</breakiterator>
+          <old>false</old>
+          <show>protected</show>
+          <quiet>true</quiet>
+          <verbose>false</verbose>
+          <author>true</author>
+          <encoding>ISO-8859-1</encoding>
+          <docfilessubdirs>false</docfilessubdirs>
+          <linksource>false</linksource>
+          <nocomment>false</nocomment>
+          <nodeprecated>false</nodeprecated>
+          <nodeprecatedlist>false</nodeprecatedlist>
+          <nohelp>false</nohelp>
+          <noindex>false</noindex>
+          <nonavbar>false</nonavbar>
+          <nosince>false</nosince>
+          <notree>false</notree>
+          <serialwarn>false</serialwarn>
+          <splitindex>false</splitindex>
+          <stylesheet>java</stylesheet>
+          <!--commas in following elements are to test MJAVADOC-93-->
+          <doctitle>doc,title</doctitle>
+          <bottom>bottom,comma test</bottom>
+          <footer>my footer, and something</footer>
+          <header>my header, and something else</header>
+          <windowtitle>Maven Javadoc Plugin, Javadoc Jar Default Config Test 1.0-SNAPSHOT API</windowtitle>
+          <groups/>
+          <tags/>
+          <use>true</use>
+          <version>true</version>
+          <debug>true</debug>
+          <failOnError>false</failOnError>
+          <generateIfEmpty>true</generateIfEmpty>
+          <reactorProjects>
+            <project implementation="org.apache.maven.plugins.javadoc.stubs.JavadocJarGenerateIfEmptyMavenProjectStub"/>
+          </reactorProjects>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>