Added: maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java?rev=1801772&view=auto ============================================================================== --- maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java (added) +++ maven/plugins/trunk/maven-javadoc-plugin/src/main/java/org/apache/maven/plugins/javadoc/AbstractJavadocMojo.java Wed Jul 12 19:59:51 2017 @@ -0,0 +1,6049 @@ +package org.apache.maven.plugins.javadoc; + +/* + * 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 static org.apache.maven.plugins.javadoc.JavadocUtil.isEmpty; +import static org.apache.maven.plugins.javadoc.JavadocUtil.isNotEmpty; +import static org.apache.maven.plugins.javadoc.JavadocUtil.toList; +import static org.apache.maven.plugins.javadoc.JavadocUtil.toRelative; +import static org.codehaus.plexus.util.IOUtil.close; + +import java.io.File; +import java.io.FileNotFoundException; +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; +import java.io.Writer; +import java.net.MalformedURLException; +import java.net.URI; +import java.net.URISyntaxException; +import java.net.URL; +import java.net.URLClassLoader; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Calendar; +import java.util.Collection; +import java.util.Collections; +import java.util.HashMap; +import java.util.HashSet; +import java.util.LinkedHashSet; +import java.util.LinkedList; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Properties; +import java.util.Set; +import java.util.StringTokenizer; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import org.apache.commons.lang3.ClassUtils; +import org.apache.commons.lang3.JavaVersion; +import org.apache.commons.lang3.SystemUtils; +import org.apache.maven.artifact.Artifact; +import org.apache.maven.artifact.factory.ArtifactFactory; +import org.apache.maven.artifact.handler.ArtifactHandler; +import org.apache.maven.artifact.handler.manager.ArtifactHandlerManager; +import org.apache.maven.artifact.metadata.ArtifactMetadataSource; +import org.apache.maven.artifact.repository.ArtifactRepository; +import org.apache.maven.artifact.resolver.ArtifactNotFoundException; +import org.apache.maven.artifact.resolver.ArtifactResolutionException; +import org.apache.maven.artifact.resolver.ArtifactResolutionResult; +import org.apache.maven.artifact.resolver.ArtifactResolver; +import org.apache.maven.artifact.versioning.ArtifactVersion; +import org.apache.maven.artifact.versioning.DefaultArtifactVersion; +import org.apache.maven.execution.MavenSession; +import org.apache.maven.model.Dependency; +import org.apache.maven.model.Plugin; +import org.apache.maven.model.Resource; +import org.apache.maven.plugin.AbstractMojo; +import org.apache.maven.plugin.MojoExecutionException; +import org.apache.maven.plugin.MojoFailureException; +import org.apache.maven.plugin.descriptor.PluginDescriptor; +import org.apache.maven.plugins.javadoc.options.BootclasspathArtifact; +import org.apache.maven.plugins.javadoc.options.DocletArtifact; +import org.apache.maven.plugins.javadoc.options.Group; +import org.apache.maven.plugins.javadoc.options.JavadocOptions; +import org.apache.maven.plugins.javadoc.options.JavadocPathArtifact; +import org.apache.maven.plugins.javadoc.options.OfflineLink; +import org.apache.maven.plugins.javadoc.options.ResourcesArtifact; +import org.apache.maven.plugins.javadoc.options.Tag; +import org.apache.maven.plugins.javadoc.options.Taglet; +import org.apache.maven.plugins.javadoc.options.TagletArtifact; +import org.apache.maven.plugins.javadoc.options.io.xpp3.JavadocOptionsXpp3Writer; +import org.apache.maven.plugins.annotations.Component; +import org.apache.maven.plugins.annotations.Parameter; +import org.apache.maven.plugins.javadoc.resolver.JavadocBundle; +import org.apache.maven.plugins.javadoc.resolver.ResourceResolver; +import org.apache.maven.plugins.javadoc.resolver.SourceResolverConfig; +import org.apache.maven.project.MavenProject; +import org.apache.maven.project.ProjectBuilder; +import org.apache.maven.project.ProjectBuildingException; +import org.apache.maven.project.artifact.InvalidDependencyVersionException; +import org.apache.maven.reporting.MavenReportException; +import org.apache.maven.settings.Proxy; +import org.apache.maven.settings.Settings; +import org.apache.maven.shared.artifact.DefaultArtifactCoordinate; +import org.apache.maven.shared.artifact.filter.resolve.AndFilter; +import org.apache.maven.shared.artifact.filter.resolve.PatternExclusionsFilter; +import org.apache.maven.shared.artifact.filter.resolve.PatternInclusionsFilter; +import org.apache.maven.shared.artifact.filter.resolve.ScopeFilter; +import org.apache.maven.shared.artifact.filter.resolve.TransformableFilter; +import org.apache.maven.shared.artifact.resolve.ArtifactResolverException; +import org.apache.maven.shared.artifact.resolve.ArtifactResult; +import org.apache.maven.shared.dependencies.DefaultDependableCoordinate; +import org.apache.maven.shared.dependencies.resolve.DependencyResolver; +import org.apache.maven.shared.dependencies.resolve.DependencyResolverException; +import org.apache.maven.shared.invoker.MavenInvocationException; +import org.apache.maven.toolchain.Toolchain; +import org.apache.maven.toolchain.ToolchainManager; +import org.apache.maven.wagon.PathUtils; +import org.codehaus.plexus.archiver.ArchiverException; +import org.codehaus.plexus.archiver.UnArchiver; +import org.codehaus.plexus.archiver.manager.ArchiverManager; +import org.codehaus.plexus.archiver.manager.NoSuchArchiverException; +import org.codehaus.plexus.components.io.fileselectors.IncludeExcludeFileSelector; +import org.codehaus.plexus.util.DirectoryScanner; +import org.codehaus.plexus.util.FileUtils; +import org.codehaus.plexus.util.IOUtil; +import org.codehaus.plexus.util.ReaderFactory; +import org.codehaus.plexus.util.StringUtils; +import org.codehaus.plexus.util.WriterFactory; +import org.codehaus.plexus.util.cli.CommandLineException; +import org.codehaus.plexus.util.cli.CommandLineUtils; +import org.codehaus.plexus.util.cli.Commandline; +import org.codehaus.plexus.util.xml.Xpp3Dom; + +/** + * Base class with majority of Javadoc functionalities. + * + * @author <a href="mailto:br...@apache.org";>Brett Porter</a> + * @author <a href="mailto:vincent.sive...@gmail.com";>Vincent Siveton</a> + * @version $Id: AbstractJavadocMojo.java 1801354 2017-07-09 08:49:46Z rfscholte $ + * @see <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html";> + * The Java API Documentation Generator, 7</a> + * @since 2.0 + */ +public abstract class AbstractJavadocMojo + extends AbstractMojo +{ + /** + * Classifier used in the name of the javadoc-options XML file, and in the resources bundle + * artifact that gets attached to the project. This one is used for non-test javadocs. + * + * @see #TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER + * @since 2.7 + */ + public static final String JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER = "javadoc-resources"; + + /** + * Classifier used in the name of the javadoc-options XML file, and in the resources bundle + * artifact that gets attached to the project. This one is used for test-javadocs. + * + * @see #JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER + * @since 2.7 + */ + public static final String TEST_JAVADOC_RESOURCES_ATTACHMENT_CLASSIFIER = "test-javadoc-resources"; + + /** + * The default Javadoc API urls according the + * <a href="http://www.oracle.com/technetwork/java/javase/documentation/api-jsp-136079.html";>Sun API + * Specifications</a>: + * <pre> + * <javaApiLinks> + * <property> + * <name>api_1.3</name> + * <value>http://docs.oracle.com/javase/1.3/docs/api/</value> + * </property> + * <property> + * <name>api_1.4</name> + * <value>http://docs.oracle.com/javase/1.4.2/docs/api/</value> + * </property> + * <property> + * <name>api_1.5</name> + * <value>http://docs.oracle.com/javase/1.5.0/docs/api/</value> + * </property> + * <property> + * <name>api_1.6</name> + * <value>http://docs.oracle.com/javase/6/docs/api/</value> + * </property> + * <property> + * <name>api_1.7</name> + * <value>http://docs.oracle.com/javase/7/docs/api/</value> + * </property> + * <property> + * <name>api_1.8</name> + * <value>http://docs.oracle.com/javase/8/docs/api/</value> + * </property> + * </javaApiLinks> + * </pre> + * + * @since 2.6 + */ + public static final Properties DEFAULT_JAVA_API_LINKS = new Properties(); + + /** + * The Javadoc script file name when <code>debug</code> parameter is on, i.e. javadoc.bat or javadoc.sh + */ + protected static final String DEBUG_JAVADOC_SCRIPT_NAME = "javadoc." + ( SystemUtils.IS_OS_WINDOWS ? "bat" : "sh" ); + + /** + * The <code>options</code> file name in the output directory when calling: + * <code>javadoc.exe(or .sh) @options @packages | @argfile | @files</code> + */ + protected static final String OPTIONS_FILE_NAME = "options"; + + /** + * The <code>packages</code> file name in the output directory when calling: + * <code>javadoc.exe(or .sh) @options @packages | @argfile | @files</code> + */ + protected static final String PACKAGES_FILE_NAME = "packages"; + + /** + * The <code>argfile</code> file name in the output directory when calling: + * <code>javadoc.exe(or .sh) @options @packages | @argfile | @files</code> + */ + protected static final String ARGFILE_FILE_NAME = "argfile"; + + /** + * The <code>files</code> file name in the output directory when calling: + * <code>javadoc.exe(or .sh) @options @packages | @argfile | @files</code> + */ + protected static final String FILES_FILE_NAME = "files"; + + /** + * The current class directory + */ + private static final String RESOURCE_DIR = ClassUtils.getPackageName( JavadocReport.class ).replace( '.', '/' ); + + /** + * Default css file name + */ + private static final String DEFAULT_CSS_NAME = "stylesheet.css"; + + /** + * Default location for css + */ + private static final String RESOURCE_CSS_DIR = RESOURCE_DIR + "/css"; + + /** + * For Javadoc options appears since Java 1.4. + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.1.html#summary";> + * What's New in Javadoc 1.4</a> + * + * @since 2.1 + */ + private static final JavadocVersion SINCE_JAVADOC_1_4 = JavadocVersion.parse( "1.4" ); + + /** + * For Javadoc options appears since Java 1.4.2. + * See <a + * href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.2.html#commandlineoptions";> + * What's New in Javadoc 1.4.2</a> + * + * @since 2.1 + */ + private static final JavadocVersion SINCE_JAVADOC_1_4_2 = JavadocVersion.parse( "1.4.2" ); + + /** + * For Javadoc options appears since Java 5.0. + * See <a + * href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.5.0.html#commandlineoptions";> + * What's New in Javadoc 5.0</a> + * + * @since 2.1 + */ + private static final JavadocVersion SINCE_JAVADOC_1_5 = JavadocVersion.parse( "1.5" ); + + /** + * For Javadoc options appears since Java 6.0. + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html";> + * Javadoc Technology</a> + * + * @since 2.4 + */ + private static final JavadocVersion SINCE_JAVADOC_1_6 = JavadocVersion.parse( "1.6" ); + + /** + * For Javadoc options appears since Java 8.0. + * See <a href="http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html";> + * Javadoc Technology</a> + * + * @since 3.0.0 + */ + private static final JavadocVersion SINCE_JAVADOC_1_8 = JavadocVersion.parse( "1.8" ); + + /** + * + */ + private static final JavadocVersion JAVA_VERSION = JavadocVersion.parse( SystemUtils.JAVA_VERSION ); + + // ---------------------------------------------------------------------- + // Mojo components + // ---------------------------------------------------------------------- + + /** + * Archiver manager + * + * @since 2.5 + */ + @Component + private ArchiverManager archiverManager; + + /** + * Factory for creating artifact objects + */ + @Component + private ArtifactFactory factory; + + /** + * Used to resolve artifacts of aggregated modules + * + * @since 2.1 + */ + @Component + private ArtifactMetadataSource artifactMetadataSource; + + /** + * Used for resolving artifacts + */ + @Component + private ArtifactResolver resolver; + + @Component + private ResourceResolver resourceResolver; + + @Component + private org.apache.maven.shared.artifact.resolve.ArtifactResolver artifactResolver; + + @Component + private ArtifactHandlerManager artifactHandlerManager; + + @Component + private DependencyResolver dependencyResolver; + + /** + * Project builder + * + * @since 3.0 + */ + @Component + private ProjectBuilder mavenProjectBuilder; + + /** */ + @Component + private ToolchainManager toolchainManager; + + // ---------------------------------------------------------------------- + // Mojo parameters + // ---------------------------------------------------------------------- + + /** + * The current build session instance. This is used for + * toolchain manager API calls. + */ + @Parameter( defaultValue = "${session}", readonly = true, required = true ) + protected MavenSession session; + + /** + * The Maven Settings. + * + * @since 2.3 + */ + @Parameter( defaultValue = "${settings}", readonly = true, required = true ) + private Settings settings; + + /** + * The Maven Project Object + */ + @Parameter( defaultValue = "${project}", readonly = true, required = true ) + protected MavenProject project; + + @Parameter( defaultValue = "${plugin}", readonly = true ) + private PluginDescriptor plugin; + + /** + * Specify if the Javadoc should operate in offline mode. + */ + @Parameter( defaultValue = "${settings.offline}", required = true, readonly = true ) + private boolean isOffline; + + /** + * Specifies the Javadoc resources directory to be included in the Javadoc (i.e. package.html, images...). + * <br/> + * Could be used in addition of <code>docfilessubdirs</code> parameter. + * <br/> + * See <a href="#docfilessubdirs">docfilessubdirs</a>. + * + * @see #docfilessubdirs + * @since 2.1 + */ + @Parameter( defaultValue = "${basedir}/src/main/javadoc" ) + private File javadocDirectory; + + /** + * Set an additional parameter(s) on the command line. This value should include quotes as necessary for + * parameters that include spaces. Useful for a custom doclet. + * + * @deprecated Does not properly support multiple options at once and has a bad name + */ + @Parameter( property = "additionalparam" ) + @Deprecated + private String additionalparam; + + /** + * Set an additional Javadoc option(s) (i.e. JVM options) on the command line. + * Example: + * <pre> + * <additionalJOption>-J-Xss128m</additionalJOption> + * </pre> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#J";>Jflag</a>. + * <br/> + * See <a href="http://java.sun.com/javase/technologies/hotspot/vmoptions.jsp";>vmoptions</a>. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html";>Networking + * Properties</a>. + * + * @since 2.3 + */ + @Parameter( property = "additionalJOption" ) + private String additionalJOption; + + /** + * Set additional JVM options for the execution of the javadoc command via the '-J' option to javadoc. + * Example: + * <pre> + * <additionalJOptions> + * <additionalJOption>-J-Xmx1g </additionalJOption> + * </additionalJOptions> + * </pre> + * @since 2.9 + */ + @Parameter + private String[] additionalJOptions; + + /** + * A list of artifacts containing resources which should be copied into the + * Javadoc output directory (like stylesheets, icons, etc.). + * <br/> + * Example: + * <pre> + * <resourcesArtifacts> + * <resourcesArtifact> + * <groupId>external.group.id</groupId> + * <artifactId>external-resources</artifactId> + * <version>1.0</version> + * </resourcesArtifact> + * </resourcesArtifacts> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/ResourcesArtifact.html">Javadoc</a>. + * <br/> + * + * @since 2.5 + */ + @Parameter( property = "resourcesArtifacts" ) + private ResourcesArtifact[] resourcesArtifacts; + + /** + * The local repository where the artifacts are located. + */ + @Parameter( property = "localRepository" ) + private ArtifactRepository localRepository; + + /** + * The projects in the reactor for aggregation report. + */ + @Parameter( property = "reactorProjects", readonly = true ) + private List<MavenProject> reactorProjects; + + /** + * Set this to <code>true</code> to debug the Javadoc plugin. With this, <code>javadoc.bat(or.sh)</code>, + * <code>options</code>, <code>@packages</code> or <code>argfile</code> files are provided in the output directory. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "debug", defaultValue = "false" ) + private boolean debug; + + /** + * Sets the absolute path of the Javadoc Tool executable to use. Since version 2.5, a mere directory specification + * is sufficient to have the plugin use "javadoc" or "javadoc.exe" respectively from this directory. + * + * @since 2.3 + */ + @Parameter( property = "javadocExecutable" ) + private String javadocExecutable; + + /** + * Version of the Javadoc Tool executable to use, ex. "1.3", "1.5". + * + * @since 2.3 + */ + @Parameter( property = "javadocVersion" ) + private String javadocVersion; + + /** + * Version of the Javadoc Tool executable to use. + */ + private JavadocVersion javadocRuntimeVersion; + + /** + * Specifies whether the Javadoc generation should be skipped. + * + * @since 2.5 + */ + @Parameter( property = "maven.javadoc.skip", defaultValue = "false" ) + protected boolean skip; + + /** + * Specifies if the build will fail if there are errors during javadoc execution or not. + * + * @since 2.5 + */ + @Parameter( property = "maven.javadoc.failOnError", defaultValue = "true" ) + protected boolean failOnError; + + /** + * Specifies to use the + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#standard";> + * options provided by the Standard Doclet</a> for a custom doclet. + * <br/> + * Example: + * <pre> + * <docletArtifacts> + * <docletArtifact> + * <groupId>com.sun.tools.doclets</groupId> + * <artifactId>doccheck</artifactId> + * <version>1.2b2</version> + * </docletArtifact> + * </docletArtifacts> + * <useStandardDocletOptions>true</useStandardDocletOptions> + * </pre> + * + * @since 2.5 + */ + @Parameter( property = "useStandardDocletOptions", defaultValue = "true" ) + protected boolean useStandardDocletOptions; + + /** + * Detect the Javadoc links for all dependencies defined in the project. The detection is based on the default + * Maven conventions, i.e.: <code>${project.url}/apidocs</code>. + * <br/> + * For instance, if the project has a dependency to + * <a href="http://commons.apache.org/lang/";>Apache Commons Lang</a> i.e.: + * <pre> + * <dependency> + * <groupId>commons-lang</groupId> + * <artifactId>commons-lang</artifactId> + * </dependency> + * </pre> + * The added Javadoc <code>-link</code> parameter will be <code>http://commons.apache.org/lang/apidocs</code>. + * + * @see #links + * @since 2.6 + */ + @Parameter( property = "detectLinks", defaultValue = "false" ) + private boolean detectLinks; + + /** + * Detect the links for all modules defined in the project. + * <br/> + * If {@link #reactorProjects} is defined in a non-aggregator way, it generates default offline links + * between modules based on the defined project's urls. For instance, if a parent project has two projects + * <code>module1</code> and <code>module2</code>, the <code>-linkoffline</code> will be: + * <br/> + * The added Javadoc <code>-linkoffline</code> parameter for <b>module1</b> will be + * <code>/absolute/path/to/</code><b>module2</b><code>/target/site/apidocs</code> + * <br/> + * The added Javadoc <code>-linkoffline</code> parameter for <b>module2</b> will be + * <code>/absolute/path/to/</code><b>module1</b><code>/target/site/apidocs</code> + * + * @see #offlineLinks + * @since 2.6 + */ + @Parameter( property = "detectOfflineLinks", defaultValue = "true" ) + private boolean detectOfflineLinks; + + /** + * Detect the Java API link for the current build, i.e. <code>http://docs.oracle.com/javase/1.4.2/docs/api/</code> + * for Java source 1.4. + * <br/> + * By default, the goal detects the Javadoc API link depending the value of the <code>source</code> + * parameter in the <code>org.apache.maven.plugins:maven-compiler-plugin</code> + * (defined in <code>${project.build.plugins}</code> or in <code>${project.build.pluginManagement}</code>), + * or try to compute it from the {@link #javadocExecutable} version. + * <br/> + * See + * <a href="./apidocs/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.html#DEFAULT_JAVA_API_LINKS">Javadoc</a> + * for the default values. + * <br/> + * + * @see #links + * @see #javaApiLinks + * @see #DEFAULT_JAVA_API_LINKS + * @since 2.6 + */ + @Parameter( property = "detectJavaApiLink", defaultValue = "true" ) + private boolean detectJavaApiLink; + + /** + * Use this parameter <b>only</b> if the <a href="http://java.sun.com/reference/api/index.html";>Sun Javadoc API</a> + * urls have been changed or to use custom urls for Javadoc API url. + * <br/> + * See + * <a href="./apidocs/org/apache/maven/plugin/javadoc/AbstractJavadocMojo.html#DEFAULT_JAVA_API_LINKS">Javadoc</a> + * for the default values. + * <br/> + * + * @see #DEFAULT_JAVA_API_LINKS + * @since 2.6 + */ + @Parameter( property = "javaApiLinks" ) + private Properties javaApiLinks; + + /** + * Flag controlling content validation of <code>package-list</code> resources. If set, the content of + * <code>package-list</code> resources will be validated. + * + * @since 2.8 + */ + @Parameter( property = "validateLinks", defaultValue = "false" ) + private boolean validateLinks; + + // ---------------------------------------------------------------------- + // Javadoc Options - all alphabetical + // ---------------------------------------------------------------------- + + /** + * Specifies the paths where the boot classes reside. The <code>bootclasspath</code> can contain multiple paths + * by separating them with a colon (<code>:</code>) or a semi-colon (<code>;</code>). + * <br/> + * See <a + * href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#bootclasspath";>bootclasspath</a>. + * <br/> + * + * @since 2.5 + */ + @Parameter( property = "bootclasspath" ) + private String bootclasspath; + + /** + * Specifies the artifacts where the boot classes reside. + * <br/> + * See <a + * href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#bootclasspath";>bootclasspath</a>. + * <br/> + * Example: + * <pre> + * <bootclasspathArtifacts> + * <bootclasspathArtifact> + * <groupId>my-groupId</groupId> + * <artifactId>my-artifactId</artifactId> + * <version>my-version</version> + * </bootclasspathArtifact> + * </bootclasspathArtifacts> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/BootclasspathArtifact.html">Javadoc</a>. + * <br/> + * + * @since 2.5 + */ + @Parameter( property = "bootclasspathArtifacts" ) + private BootclasspathArtifact[] bootclasspathArtifacts; + + /** + * Uses the sentence break iterator to determine the end of the first sentence. + * <br/> + * See <a + * href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#breakiterator";>breakiterator</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + * <br/> + */ + @Parameter( property = "breakiterator", defaultValue = "false" ) + private boolean breakiterator; + + /** + * Specifies the class file that starts the doclet used in generating the documentation. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#doclet";>doclet</a>. + */ + @Parameter( property = "doclet" ) + private String doclet; + + /** + * Specifies the artifact containing the doclet starting class file (specified with the <code>-doclet</code> + * option). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docletpath";>docletpath</a>. + * <br/> + * Example: + * <pre> + * <docletArtifact> + * <groupId>com.sun.tools.doclets</groupId> + * <artifactId>doccheck</artifactId> + * <version>1.2b2</version> + * </docletArtifact> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/DocletArtifact.html">Javadoc</a>. + * <br/> + */ + @Parameter( property = "docletArtifact" ) + private DocletArtifact docletArtifact; + + /** + * Specifies multiple artifacts containing the path for the doclet starting class file (specified with the + * <code>-doclet</code> option). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docletpath";>docletpath</a>. + * <br/> + * Example: + * <pre> + * <docletArtifacts> + * <docletArtifact> + * <groupId>com.sun.tools.doclets</groupId> + * <artifactId>doccheck</artifactId> + * <version>1.2b2</version> + * </docletArtifact> + * </docletArtifacts> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/DocletArtifact.html">Javadoc</a>. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "docletArtifacts" ) + private DocletArtifact[] docletArtifacts; + + /** + * Specifies the path to the doclet starting class file (specified with the <code>-doclet</code> option) and + * any jar files it depends on. The <code>docletPath</code> can contain multiple paths by separating them with + * a colon (<code>:</code>) or a semi-colon (<code>;</code>). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docletpath";>docletpath</a>. + */ + @Parameter( property = "docletPath" ) + private String docletPath; + + /** + * Specifies the encoding name of the source files. If not specificed, the encoding value will be the value of the + * <code>file.encoding</code> system property. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#encoding";>encoding</a>. + * <br/> + * <b>Note</b>: In 2.4, the default value was locked to <code>ISO-8859-1</code> to ensure reproducing build, but + * this was reverted in 2.5. + * <br/> + */ + @Parameter( property = "encoding", defaultValue = "${project.build.sourceEncoding}" ) + private String encoding; + + /** + * Unconditionally excludes the specified packages and their subpackages from the list formed by + * <code>-subpackages</code>. Multiple packages can be separated by commas (<code>,</code>), colons (<code>:</code>) + * or semicolons (<code>;</code>). + * <br/> + * Example: + * <pre> + * <excludePackageNames>*.internal:org.acme.exclude1.*:org.acme.exclude2</excludePackageNames> + * </pre> + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#exclude";>exclude</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + */ + @Parameter( property = "excludePackageNames" ) + private String excludePackageNames; + + /** + * Specifies the directories where extension classes reside. Separate directories in <code>extdirs</code> with a + * colon (<code>:</code>) or a semi-colon (<code>;</code>). + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#extdirs";>extdirs</a>. + */ + @Parameter( property = "extdirs" ) + private String extdirs; + + /** + * Specifies the locale that javadoc uses when generating documentation. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#locale";>locale</a>. + */ + @Parameter( property = "locale" ) + private String locale; + + /** + * Specifies the maximum Java heap size to be used when launching the Javadoc tool. + * JVMs refer to this property as the <code>-Xmx</code> parameter. Example: '512' or '512m'. + * The memory unit depends on the JVM used. The units supported could be: <code>k</code>, <code>kb</code>, + * <code>m</code>, <code>mb</code>, <code>g</code>, <code>gb</code>, <code>t</code>, <code>tb</code>. + * If no unit specified, the default unit is <code>m</code>. + */ + @Parameter( property = "maxmemory" ) + private String maxmemory; + + /** + * Specifies the minimum Java heap size to be used when launching the Javadoc tool. + * JVMs refer to this property as the <code>-Xms</code> parameter. Example: '512' or '512m'. + * The memory unit depends on the JVM used. The units supported could be: <code>k</code>, <code>kb</code>, + * <code>m</code>, <code>mb</code>, <code>g</code>, <code>gb</code>, <code>t</code>, <code>tb</code>. + * If no unit specified, the default unit is <code>m</code>. + */ + @Parameter( property = "minmemory" ) + private String minmemory; + + /** + * This option creates documentation with the appearance and functionality of documentation generated by + * Javadoc 1.1. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#1.1";>1.1</a>. + * <br/> + */ + @Parameter( property = "old", defaultValue = "false" ) + private boolean old; + + /** + * Specifies that javadoc should retrieve the text for the overview documentation from the "source" file + * specified by path/filename and place it on the Overview page (overview-summary.html). + * <br/> + * <b>Note</b>: could be in conflict with <nooverview/>. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#overview";>overview</a>. + * <br/> + */ + @Parameter( property = "overview", defaultValue = "${basedir}/src/main/javadoc/overview.html" ) + private File overview; + + /** + * Shuts off non-error and non-warning messages, leaving only the warnings and errors appear, making them + * easier to view. + * <br/> + * Note: was a standard doclet in Java 1.4.2 (refer to bug ID + * <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4714350";>4714350</a>). + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#quiet";>quiet</a>. + * <br/> + * Since Java 5.0. + * <br/> + */ + @Parameter( property = "quiet", defaultValue = "false" ) + private boolean quiet; + + /** + * Specifies the access level for classes and members to show in the Javadocs. + * Possible values are: + * <ul> + * <li><a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#public";>public</a> + * (shows only public classes and members)</li> + * <li><a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#protected";>protected</a> + * (shows only public and protected classes and members)</li> + * <li><a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#package";>package</a> + * (shows all classes and members not marked private)</li> + * <li><a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#private";>private</a> + * (shows all classes and members)</li> + * </ul> + * <br/> + */ + @Parameter( property = "show", defaultValue = "protected" ) + private String show; + + /** + * Necessary to enable javadoc to handle assertions introduced in J2SE v 1.4 source code or generics introduced in + * J2SE v5. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#source";>source</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + */ + @Parameter( property = "source" ) + private String source; + + /** + * Specifies the source paths where the subpackages are located. The <code>sourcepath</code> can contain + * multiple paths by separating them with a colon (<code>:</code>) or a semi-colon (<code>;</code>). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#sourcepath";>sourcepath</a>. + */ + @Parameter( property = "sourcepath" ) + private String sourcepath; + + /** + * Specifies the package directory where javadoc will be executed. Multiple packages can be separated by + * colons (<code>:</code>). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#subpackages";>subpackages</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + */ + @Parameter( property = "subpackages" ) + private String subpackages; + + /** + * Provides more detailed messages while javadoc is running. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#verbose";>verbose</a>. + * <br/> + */ + @Parameter( property = "verbose", defaultValue = "false" ) + private boolean verbose; + + // ---------------------------------------------------------------------- + // Standard Doclet Options - all alphabetical + // ---------------------------------------------------------------------- + + /** + * Specifies whether or not the author text is included in the generated Javadocs. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#author";>author</a>. + * <br/> + */ + @Parameter( property = "author", defaultValue = "true" ) + private boolean author; + + /** + * Specifies the text to be placed at the bottom of each output file.<br/> + * If you want to use html you have to put it in a CDATA section, <br/> + * eg. <code><![CDATA[Copyright 2005, <a href="http://www.mycompany.com";>MyCompany, Inc.<a>]]></code> + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#bottom";>bottom</a>. + * <br/> + */ + @Parameter( property = "bottom", + defaultValue = "Copyright © {inceptionYear}–{currentYear} {organizationName}. " + + "All rights reserved." ) + private String bottom; + + /** + * Specifies the HTML character set for this document. If not specificed, the charset value will be the value of + * the <code>docencoding</code> parameter. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#charset";>charset</a>. + * <br/> + */ + @Parameter( property = "charset" ) + private String charset; + + /** + * Specifies the encoding of the generated HTML files. If not specificed, the docencoding value will be + * <code>UTF-8</code>. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docencoding";>docencoding</a>. + */ + @Parameter( property = "docencoding", defaultValue = "${project.reporting.outputEncoding}" ) + private String docencoding; + + /** + * Enables deep copying of the <code>**/doc-files</code> directories and the specifc <code>resources</code> + * directory from the <code>javadocDirectory</code> directory (for instance, + * <code>src/main/javadoc/com/mycompany/myapp/doc-files</code> and <code>src/main/javadoc/resources</code>). + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docfilessubdirs";> + * docfilessubdirs</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + * <br/> + * See <a href="#javadocDirectory">javadocDirectory</a>. + * <br/> + * + * @see #excludedocfilessubdir + * @see #javadocDirectory + */ + @Parameter( property = "docfilessubdirs", defaultValue = "false" ) + private boolean docfilessubdirs; + + /** + * Specifies specific checks to be performed on Javadoc comments. + * <br/> + * See <a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#BEJEFABE";>doclint</a>. + * + * @since 3.0.0 + */ + @Parameter( property = "doclint" ) + private String doclint; + + /** + * Specifies the title to be placed near the top of the overview summary file. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#doctitle";>doctitle</a>. + * <br/> + */ + @Parameter( property = "doctitle", defaultValue = "${project.name} ${project.version} API" ) + private String doctitle; + + /** + * Excludes any "doc-files" subdirectories with the given names. Multiple patterns can be excluded + * by separating them with colons (<code>:</code>). + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#excludedocfilessubdir";> + * excludedocfilessubdir</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + * + * @see #docfilessubdirs + */ + @Parameter( property = "excludedocfilessubdir" ) + private String excludedocfilessubdir; + + /** + * Specifies the footer text to be placed at the bottom of each output file. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#footer";>footer</a>. + */ + @Parameter( property = "footer" ) + private String footer; + + /** + * Separates packages on the overview page into whatever groups you specify, one group per table. The + * packages pattern can be any package name, or can be the start of any package name followed by an asterisk + * (<code>*</code>) meaning "match any characters". Multiple patterns can be included in a group + * by separating them with colons (<code>:</code>). + * <br/> + * Example: + * <pre> + * <groups> + * <group> + * <title>Core Packages</title> + * <!-- To includes java.lang, java.lang.ref, + * java.lang.reflect and only java.util + * (i.e. not java.util.jar) --> + * <packages>java.lang*:java.util</packages> + * </group> + * <group> + * <title>Extension Packages</title> + * <!-- To include javax.accessibility, + * javax.crypto, ... (among others) --> + * <packages>javax.*</packages> + * </group> + * </groups> + * </pre> + * <b>Note</b>: using <code>java.lang.*</code> for <code>packages</code> would omit the <code>java.lang</code> + * package but using <code>java.lang*</code> will include it. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#group";>group</a>. + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/Group.html">Javadoc</a>. + * <br/> + */ + @Parameter( property = "groups" ) + private Group[] groups; + + /** + * Specifies the header text to be placed at the top of each output file. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#header";>header</a>. + */ + @Parameter( property = "header" ) + private String header; + + /** + * Specifies the path of an alternate help file path\filename that the HELP link in the top and bottom + * navigation bars link to. + * <br/> + * <b>Note</b>: could be in conflict with <nohelp/>. + * <br/> + * The <code>helpfile</code> could be an absolute File path. + * <br/> + * Since 2.6, it could be also be a path from a resource in the current project source directories + * (i.e. <code>src/main/java</code>, <code>src/main/resources</code> or <code>src/main/javadoc</code>) + * or from a resource in the Javadoc plugin dependencies, for instance: + * <pre> + * <helpfile>path/to/your/resource/yourhelp-doc.html</helpfile> + * </pre> + * Where <code>path/to/your/resource/yourhelp-doc.html</code> could be in <code>src/main/javadoc</code>. + * <pre> + * <build> + * <plugins> + * <plugin> + * <groupId>org.apache.maven.plugins</groupId> + * <artifactId>maven-javadoc-plugin</artifactId> + * <configuration> + * <helpfile>path/to/your/resource/yourhelp-doc.html</helpfile> + * ... + * </configuration> + * <dependencies> + * <dependency> + * <groupId>groupId</groupId> + * <artifactId>artifactId</artifactId> + * <version>version</version> + * </dependency> + * </dependencies> + * </plugin> + * ... + * <plugins> + * </build> + * </pre> + * Where <code>path/to/your/resource/yourhelp-doc.html</code> is defined in the + * <code>groupId:artifactId:version</code> javadoc plugin dependency. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#helpfile";>helpfile</a>. + */ + @Parameter( property = "helpfile" ) + private String helpfile; + + /** + * Adds HTML meta keyword tags to the generated file for each class. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#keywords";>keywords</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.2.html#commandlineoptions";> + * Java 1.4.2</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.5.0.html#commandlineoptions";> + * Java 5.0</a>. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "keywords", defaultValue = "false" ) + private boolean keywords; + + /** + * Creates links to existing javadoc-generated documentation of external referenced classes. + * <br/> + * <b>Notes</b>: + * <ol> + * <li>only used if {@link #isOffline} is set to <code>false</code>.</li> + * <li>all given links should have a fetchable <code>/package-list</code> file. For instance: + * <pre> + * <links> + * <link>http://docs.oracle.com/javase/1.4.2/docs/api</link> + * <links> + * </pre> + * will be used because <code>http://docs.oracle.com/javase/1.4.2/docs/api/package-list</code> exists.</li> + * <li>if {@link #detectLinks} is defined, the links between the project dependencies are + * automatically added.</li> + * <li>if {@link #detectJavaApiLink} is defined, a Java API link, based on the Java version of the + * project's sources, will be added automatically.</li> + * </ol> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#link";>link</a>. + * + * @see #detectLinks + * @see #detectJavaApiLink + */ + @Parameter( property = "links" ) + protected ArrayList<String> links; + + /** + * Creates an HTML version of each source file (with line numbers) and adds links to them from the standard + * HTML documentation. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linksource";>linksource</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + * <br/> + */ + @Parameter( property = "linksource", defaultValue = "false" ) + private boolean linksource; + + /** + * Suppress the entire comment body, including the main description and all tags, generating only declarations. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nocomment";>nocomment</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + * <br/> + */ + @Parameter( property = "nocomment", defaultValue = "false" ) + private boolean nocomment; + + /** + * Prevents the generation of any deprecated API at all in the documentation. + * <br/> + * See + * <a + * href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nodeprecated";>nodeprecated</a>. + * <br/> + */ + @Parameter( property = "nodeprecated", defaultValue = "false" ) + private boolean nodeprecated; + + /** + * Prevents the generation of the file containing the list of deprecated APIs (deprecated-list.html) and the + * link in the navigation bar to that page. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nodeprecatedlist";> + * nodeprecatedlist</a>. + * <br/> + */ + @Parameter( property = "nodeprecatedlist", defaultValue = "false" ) + private boolean nodeprecatedlist; + + /** + * Omits the HELP link in the navigation bars at the top and bottom of each page of output. + * <br/> + * <b>Note</b>: could be in conflict with <helpfile/>. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nohelp";>nohelp</a>. + * <br/> + */ + @Parameter( property = "nohelp", defaultValue = "false" ) + private boolean nohelp; + + /** + * Omits the index from the generated docs. + * <br/> + * <b>Note</b>: could be in conflict with <splitindex/>. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#noindex";>noindex</a>. + * <br/> + */ + @Parameter( property = "noindex", defaultValue = "false" ) + private boolean noindex; + + /** + * Omits the navigation bar from the generated docs. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nonavbar";>nonavbar</a>. + * <br/> + */ + @Parameter( property = "nonavbar", defaultValue = "false" ) + private boolean nonavbar; + + /** + * Omits the entire overview page from the generated docs. + * <br/> + * <b>Note</b>: could be in conflict with <overview/>. + * <br/> + * Standard Doclet undocumented option. + * <br/> + * + * @since 2.4 + */ + @Parameter( property = "nooverview", defaultValue = "false" ) + private boolean nooverview; + + /** + * Omits qualifying package name from ahead of class names in output. + * Example: + * <pre> + * <noqualifier>all</noqualifier> + * or + * <noqualifier>packagename1:packagename2</noqualifier> + * </pre> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#noqualifier";>noqualifier</a>. + * <br/> + * Since <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java + * 1.4</a>. + */ + @Parameter( property = "noqualifier" ) + private String noqualifier; + + /** + * Omits from the generated docs the "Since" sections associated with the since tags. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#nosince";>nosince</a>. + * <br/> + */ + @Parameter( property = "nosince", defaultValue = "false" ) + private boolean nosince; + + /** + * Suppresses the timestamp, which is hidden in an HTML comment in the generated HTML near the top of each page. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#notimestamp";>notimestamp</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.5.0.html#commandlineoptions";> + * Java 5.0</a>. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "notimestamp", defaultValue = "false" ) + private boolean notimestamp; + + /** + * Omits the class/interface hierarchy pages from the generated docs. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#notree";>notree</a>. + * <br/> + */ + @Parameter( property = "notree", defaultValue = "false" ) + private boolean notree; + + /** + * This option is a variation of <code>-link</code>; they both create links to javadoc-generated documentation + * for external referenced classes. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linkoffline";>linkoffline</a>. + * <br/> + * Example: + * <pre> + * <offlineLinks> + * <offlineLink> + * <url>http://docs.oracle.com/javase/1.5.0/docs/api/</url> + * <location>../javadoc/jdk-5.0/</location> + * </offlineLink> + * </offlineLinks> + * </pre> + * <br/> + * <b>Note</b>: if {@link #detectOfflineLinks} is defined, the offline links between the project modules are + * automatically added if the goal is calling in a non-aggregator way. + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/OfflineLink.html">Javadoc</a>. + * <br/> + */ + @Parameter( property = "offlineLinks" ) + private OfflineLink[] offlineLinks; + + /** + * Specifies the destination directory where javadoc saves the generated HTML files. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#d";>d</a>. + * <br/> + */ + @Parameter( property = "destDir", alias = "destDir", defaultValue = "${project.build.directory}/apidocs", + required = true ) + protected File outputDirectory; + + /** + * Specify the text for upper left frame. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.2.html#commandlineoptions";> + * Java 1.4.2</a>. + * + * @since 2.1 + */ + @Parameter( property = "packagesheader" ) + private String packagesheader; + + /** + * Generates compile-time warnings for missing serial tags. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#serialwarn";>serialwarn</a> + * <br/> + */ + @Parameter( property = "serialwarn", defaultValue = "false" ) + private boolean serialwarn; + + /** + * Specify the number of spaces each tab takes up in the source. If no tab is used in source, the default + * space is used. + * <br/> + * Note: was <code>linksourcetab</code> in Java 1.4.2 (refer to bug ID + * <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4788919";>4788919</a>). + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.2.html#commandlineoptions";> + * 1.4.2</a>. + * <br/> + * Since Java 5.0. + * + * @since 2.1 + */ + @Parameter( property = "sourcetab", alias = "linksourcetab" ) + private int sourcetab; + + /** + * Splits the index file into multiple files, alphabetically, one file per letter, plus a file for any index + * entries that start with non-alphabetical characters. + * <br/> + * <b>Note</b>: could be in conflict with <noindex/>. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#splitindex";>splitindex</a>. + * <br/> + */ + @Parameter( property = "splitindex", defaultValue = "false" ) + private boolean splitindex; + + /** + * Specifies whether the stylesheet to be used is the <code>maven</code>'s javadoc stylesheet or + * <code>java</code>'s default stylesheet when a <i>stylesheetfile</i> parameter is not specified. + * <br/> + * Possible values: <code>maven<code> or <code>java</code>. + * <br/> + */ + @Parameter( property = "stylesheet", defaultValue = "java" ) + private String stylesheet; + + /** + * Specifies the path of an alternate HTML stylesheet file. + * <br/> + * The <code>stylesheetfile</code> could be an absolute File path. + * <br/> + * Since 2.6, it could be also be a path from a resource in the current project source directories + * (i.e. <code>src/main/java</code>, <code>src/main/resources</code> or <code>src/main/javadoc</code>) + * or from a resource in the Javadoc plugin dependencies, for instance: + * <pre> + * <stylesheetfile>path/to/your/resource/yourstylesheet.css</stylesheetfile> + * </pre> + * Where <code>path/to/your/resource/yourstylesheet.css</code> could be in <code>src/main/javadoc</code>. + * <pre> + * <build> + * <plugins> + * <plugin> + * <groupId>org.apache.maven.plugins</groupId> + * <artifactId>maven-javadoc-plugin</artifactId> + * <configuration> + * <stylesheetfile>path/to/your/resource/yourstylesheet.css</stylesheetfile> + * ... + * </configuration> + * <dependencies> + * <dependency> + * <groupId>groupId</groupId> + * <artifactId>artifactId</artifactId> + * <version>version</version> + * </dependency> + * </dependencies> + * </plugin> + * ... + * <plugins> + * </build> + * </pre> + * Where <code>path/to/your/resource/yourstylesheet.css</code> is defined in the + * <code>groupId:artifactId:version</code> javadoc plugin dependency. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#stylesheetfile";> + * stylesheetfile</a>. + */ + @Parameter( property = "stylesheetfile" ) + private String stylesheetfile; + + /** + * Specifies the class file that starts the taglet used in generating the documentation for that tag. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#taglet";>taglet</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java 1.4</a>. + */ + @Parameter( property = "taglet" ) + private String taglet; + + /** + * Specifies the Taglet artifact containing the taglet class files (.class). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tagletpath";>tagletpath</a>. + * <br/> + * Example: + * <pre> + * <taglets> + * <taglet> + * <tagletClass>com.sun.tools.doclets.ToDoTaglet</tagletClass> + * </taglet> + * <taglet> + * <tagletClass>package.to.AnotherTagletClass</tagletClass> + * </taglet> + * ... + * </taglets> + * <tagletArtifact> + * <groupId>group-Taglet</groupId> + * <artifactId>artifact-Taglet</artifactId> + * <version>version-Taglet</version> + * </tagletArtifact> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/TagletArtifact.html">Javadoc</a>. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "tagletArtifact" ) + private TagletArtifact tagletArtifact; + + /** + * Specifies several Taglet artifacts containing the taglet class files (.class). These taglets class names will be + * auto-detect and so no need to specify them. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#taglet";>taglet</a>. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tagletpath";>tagletpath</a>. + * <br/> + * Example: + * <pre> + * <tagletArtifacts> + * <tagletArtifact> + * <groupId>group-Taglet</groupId> + * <artifactId>artifact-Taglet</artifactId> + * <version>version-Taglet</version> + * </tagletArtifact> + * ... + * </tagletArtifacts> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/TagletArtifact.html">Javadoc</a>. + * <br/> + * + * @since 2.5 + */ + @Parameter( property = "tagletArtifacts" ) + private TagletArtifact[] tagletArtifacts; + + /** + * Specifies the search paths for finding taglet class files (.class). The <code>tagletpath</code> can contain + * multiple paths by separating them with a colon (<code>:</code>) or a semi-colon (<code>;</code>). + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tagletpath";>tagletpath</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java 1.4</a>. + */ + @Parameter( property = "tagletpath" ) + private String tagletpath; + + /** + * Enables the Javadoc tool to interpret multiple taglets. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#taglet";>taglet</a>. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tagletpath";>tagletpath</a>. + * <br/> + * Example: + * <pre> + * <taglets> + * <taglet> + * <tagletClass>com.sun.tools.doclets.ToDoTaglet</tagletClass> + * <!--<tagletpath>/home/taglets</tagletpath>--> + * <tagletArtifact> + * <groupId>group-Taglet</groupId> + * <artifactId>artifact-Taglet</artifactId> + * <version>version-Taglet</version> + * </tagletArtifact> + * </taglet> + * </taglets> + * </pre> + * <br/> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/Taglet.html">Javadoc</a>. + * <br/> + * + * @since 2.1 + */ + @Parameter( property = "taglets" ) + private Taglet[] taglets; + + /** + * Enables the Javadoc tool to interpret a simple, one-argument custom block tag tagname in doc comments. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tag";>tag</a>. + * <br/> + * Since + * <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/whatsnew-1.4.html#summary";>Java 1.4</a>. + * <br/> + * Example: + * <pre> + * <tags> + * <tag> + * <name>todo</name> + * <placement>a</placement> + * <head>To Do:</head> + * </tag> + * </tags> + * </pre> + * <b>Note</b>: the placement should be a combinaison of Xaoptcmf letters: + * <ul> + * <li><b><code>X</code></b> (disable tag)</li> + * <li><b><code>a</code></b> (all)</li> + * <li><b><code>o</code></b> (overview)</li> + * <li><b><code>p</code></b> (packages)</li> + * <li><b><code>t</code></b> (types, that is classes and interfaces)</li> + * <li><b><code>c</code></b> (constructors)</li> + * <li><b><code>m</code></b> (methods)</li> + * <li><b><code>f</code></b> (fields)</li> + * </ul> + * See <a href="./apidocs/org/apache/maven/plugin/javadoc/options/Tag.html">Javadoc</a>. + * <br/> + */ + @Parameter( property = "tags" ) + private Tag[] tags; + + /** + * Specifies the top text to be placed at the top of each output file. + * <br/> + * See <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6227616";>6227616</a>. + * <br/> + * Since Java 6.0 + * + * @since 2.4 + */ + @Parameter( property = "top" ) + private String top; + + /** + * Includes one "Use" page for each documented class and package. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#use";>use</a>. + * <br/> + */ + @Parameter( property = "use", defaultValue = "true" ) + private boolean use; + + /** + * Includes the version text in the generated docs. + * <br/> + * See <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#version";>version</a>. + * <br/> + */ + @Parameter( property = "version", defaultValue = "true" ) + private boolean version; + + /** + * Specifies the title to be placed in the HTML title tag. + * <br/> + * See + * <a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#windowtitle";>windowtitle</a>. + * <br/> + */ + @Parameter( property = "windowtitle", defaultValue = "${project.name} ${project.version} API" ) + private String windowtitle; + + /** + * Whether dependency -sources jars should be resolved and included as source paths for javadoc generation. + * This is useful when creating javadocs for a distribution project. + * + * @since 2.7 + */ + @Parameter( defaultValue = "false" ) + private boolean includeDependencySources; + + /** + * Directory where unpacked project sources / test-sources should be cached. + * + * @see #includeDependencySources + * @since 2.7 + */ + @Parameter( defaultValue = "${project.build.directory}/distro-javadoc-sources" ) + private File sourceDependencyCacheDir; + + /** + * Whether to include transitive dependencies in the list of dependency -sources jars to include + * in this javadoc run. + * + * @see #includeDependencySources + * @since 2.7 + */ + @Parameter( defaultValue = "false" ) + private boolean includeTransitiveDependencySources; + + /** + * List of included dependency-source patterns. Example: <code>org.apache.maven:*</code> + * + * @see #includeDependencySources + * @since 2.7 + */ + @Parameter + private List<String> dependencySourceIncludes; + + /** + * List of excluded dependency-source patterns. Example: <code>org.apache.maven.shared:*</code> + * + * @see #includeDependencySources + * @since 2.7 + */ + @Parameter + private List<String> dependencySourceExcludes; + + /** + * Directory into which assembled {@link JavadocOptions} instances will be written before they + * are added to javadoc resources bundles. + * + * @since 2.7 + */ + @Parameter( defaultValue = "${project.build.directory}/javadoc-bundle-options", readonly = true ) + private File javadocOptionsDir; + + /** + * Transient variable to allow lazy-resolution of javadoc bundles from dependencies, so they can + * be used at various points in the javadoc generation process. + * + * @since 2.7 + */ + private transient List<JavadocBundle> dependencyJavadocBundles; + + /** + * Capability to add additional dependencies to the javadoc classpath. + * Example: + * <pre> + * <additionalDependencies> + * <additionalDependency> + * <groupId>geronimo-spec</groupId> + * <artifactId>geronimo-spec-jta</artifactId> + * <version>1.0.1B-rc4:</version> + * </additionalDependency> + * </additionalDependencies> + * </pre> + * + * @since 2.8.1 + */ + @Parameter + private List<AdditionalDependency> additionalDependencies; + + /** + * Include filters on the source files. Default is **\/\*.java. + * These are ignored if you specify subpackages or subpackage excludes. + */ + @Parameter + private List<String> sourceFileIncludes; + + /** + * exclude filters on the source files. + * These are ignored if you specify subpackages or subpackage excludes. + */ + @Parameter + private List<String> sourceFileExcludes; + + /** + * To apply the security fix on generated javadoc see http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1571 + * @since 2.9.1 + */ + @Parameter( defaultValue = "true", property = "maven.javadoc.applyJavadocSecurityFix" ) + private boolean applyJavadocSecurityFix = true; + + // ---------------------------------------------------------------------- + // static + // ---------------------------------------------------------------------- + + static + { + DEFAULT_JAVA_API_LINKS.put( "api_1.3", "http://docs.oracle.com/javase/1.3/docs/api/"; ); + DEFAULT_JAVA_API_LINKS.put( "api_1.4", "http://docs.oracle.com/javase/1.4.2/docs/api/"; ); + DEFAULT_JAVA_API_LINKS.put( "api_1.5", "http://docs.oracle.com/javase/1.5.0/docs/api/"; ); + DEFAULT_JAVA_API_LINKS.put( "api_1.6", "http://docs.oracle.com/javase/6/docs/api/"; ); + DEFAULT_JAVA_API_LINKS.put( "api_1.7", "http://docs.oracle.com/javase/7/docs/api/"; ); + DEFAULT_JAVA_API_LINKS.put( "api_1.8", "http://docs.oracle.com/javase/8/docs/api/"; ); + } + + // ---------------------------------------------------------------------- + // protected methods + // ---------------------------------------------------------------------- + + /** + * Indicates whether this goal is flagged with <code>@aggregator</code>. + * + * @return <code>true</code> if the goal is designed as an aggregator, <code>false</code> otherwise. + * @see AggregatorJavadocReport + * @see AggregatorTestJavadocReport + */ + protected boolean isAggregator() + { + return false; + } + + /** + * Indicates whether this goal generates documentation for the <code>Java Test code</code>. + * + * @return <code>true</code> if the goal generates Test Javadocs, <code>false</code> otherwise. + */ + protected boolean isTest() + { + return false; + } + + /** + * @return the output directory + */ + protected String getOutputDirectory() + { + return outputDirectory.getAbsoluteFile().toString(); + } + + protected MavenProject getProject() + { + return project; + } + + /** + * @param p not null maven project + * @return the list of directories where compiled classes are placed for the given project. These dirs are + * added in the javadoc classpath. + */ + protected List<String> getProjectBuildOutputDirs( MavenProject p ) + { + if ( StringUtils.isEmpty( p.getBuild().getOutputDirectory() ) ) + { + return Collections.emptyList(); + } + + return Collections.singletonList( p.getBuild().getOutputDirectory() ); + } + + /** + * @param p not null maven project + * @return the list of source paths for the given project + */ + protected List<String> getProjectSourceRoots( MavenProject p ) + { + if ( "pom".equals( p.getPackaging().toLowerCase() ) ) + { + return Collections.emptyList(); + } + + return ( p.getCompileSourceRoots() == null + ? Collections.<String>emptyList() + : new LinkedList<String>( p.getCompileSourceRoots() ) ); + } + + /** + * @param p not null maven project + * @return the list of source paths for the execution project of the given project + */ + protected List<String> getExecutionProjectSourceRoots( MavenProject p ) + { + if ( "pom".equals( p.getExecutionProject().getPackaging().toLowerCase() ) ) + { + return Collections.emptyList(); + } + + return ( p.getExecutionProject().getCompileSourceRoots() == null + ? Collections.<String>emptyList() + : new LinkedList<String>( p.getExecutionProject().getCompileSourceRoots() ) ); + } + + /** + * @param p not null maven project + * @return the list of artifacts for the given project + */ + protected List<Artifact> getProjectArtifacts( MavenProject p ) + { + return ( p.getCompileArtifacts() == null + ? Collections.<Artifact>emptyList() + : new LinkedList<Artifact>( p.getCompileArtifacts() ) ); + } + + /** + * @return the current javadoc directory + */ + protected File getJavadocDirectory() + { + return javadocDirectory; + } + + /** + * @return the doclint specific checks configuration + */ + protected String getDoclint() + { + return doclint; + } + + /** + * @return the title to be placed near the top of the overview summary file + */ + protected String getDoctitle() + { + return doctitle; + } + + /** + * @return the overview documentation file from the user parameter or from the <code>javadocdirectory</code> + */ + protected File getOverview() + { + return overview; + } + + /** + * @return the title to be placed in the HTML title tag + */ + protected String getWindowtitle() + { + return windowtitle; + } + + /** + * @return the charset attribute or the value of {@link #getDocencoding()} if <code>null</code>. + */ + private String getCharset() + { + return ( StringUtils.isEmpty( charset ) ) ? getDocencoding() : charset; + } + + /** + * @return the docencoding attribute or <code>UTF-8</code> if <code>null</code>. + */ + private String getDocencoding() + { + return ( StringUtils.isEmpty( docencoding ) ) ? ReaderFactory.UTF_8 : docencoding; + } + + /** + * @return the encoding attribute or the value of <code>file.encoding</code> system property if <code>null</code>. + */ + private String getEncoding() + { + return ( StringUtils.isEmpty( encoding ) ) ? ReaderFactory.FILE_ENCODING : encoding; + } + + @Override + public void execute() + throws MojoExecutionException, MojoFailureException + { + verifyRemovedParameter( "aggregator" ); + verifyRemovedParameter( "proxyHost" ); + verifyRemovedParameter( "proxyPort" ); + + doExecute(); + } + + abstract void doExecute() throws MojoExecutionException, MojoFailureException; + + private void verifyRemovedParameter( String paramName ) + { + Object pluginConfiguration = plugin.getPlugin().getConfiguration(); + if ( pluginConfiguration instanceof Xpp3Dom ) + { + Xpp3Dom configDom = (Xpp3Dom) pluginConfiguration; + + if ( configDom.getChild( paramName ) != null ) + { + throw new IllegalArgumentException( "parameter '" + paramName + + "' has been removed from the plugin, please verify documentation." ); + } + } + } + + /** + * The <a href="package-summary.html">package documentation</a> details the + * Javadoc Options used by this Plugin. + * + * @param unusedLocale the wanted locale (actually unused). + * @throws MavenReportException if any + */ + protected void executeReport( Locale unusedLocale ) + throws MavenReportException + { + if ( skip ) + { + getLog().info( "Skipping javadoc generation" ); + return; + } + + if ( isAggregator() && !project.isExecutionRoot() ) + { + return; + } + + if ( getLog().isDebugEnabled() ) + { + this.debug = true; + } + + // NOTE: Always generate this file, to allow javadocs from modules to be aggregated via + // useDependencySources in a distro module build. + try + { + buildJavadocOptions(); + } + catch ( IOException e ) + { + throw new MavenReportException( "Failed to generate javadoc options file: " + e.getMessage(), e ); + } + + List<String> sourcePaths = getSourcePaths(); + List<String> files = getFiles( sourcePaths ); + if ( !canGenerateReport( files ) ) + { + return; + } + + List<String> packageNames = getPackageNames( sourcePaths, files ); + List<String> filesWithUnnamedPackages = getFilesWithUnnamedPackages( sourcePaths, files ); + + // ---------------------------------------------------------------------- + // Find the javadoc executable and version + // ---------------------------------------------------------------------- + + String jExecutable; + try + { + jExecutable = getJavadocExecutable(); + } + catch ( IOException e ) + { + throw new MavenReportException( "Unable to find javadoc command: " + e.getMessage(), e ); + } + setFJavadocVersion( new File( jExecutable ) ); + + // ---------------------------------------------------------------------- + // 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 + // ---------------------------------------------------------------------- + + copyAllResources( javadocOutputDirectory ); + + // ---------------------------------------------------------------------- + // Create command line for Javadoc + // ---------------------------------------------------------------------- + + Commandline cmd = new Commandline(); + cmd.getShell().setQuotedArgumentsEnabled( false ); // for Javadoc JVM args + cmd.setWorkingDirectory( javadocOutputDirectory.getAbsolutePath() ); + cmd.setExecutable( jExecutable ); + + // ---------------------------------------------------------------------- + // Wrap Javadoc JVM args + // ---------------------------------------------------------------------- + + addMemoryArg( cmd, "-Xmx", this.maxmemory ); + addMemoryArg( cmd, "-Xms", this.minmemory ); + addProxyArg( cmd ); + + if ( StringUtils.isNotEmpty( additionalJOption ) ) + { + cmd.createArg().setValue( additionalJOption ); + } + + if ( additionalJOptions != null && additionalJOptions.length != 0 ) + { + for ( String jo : additionalJOptions ) + { + cmd.createArg().setValue( jo ); + } + } + + List<String> arguments = new ArrayList<String>(); + + // ---------------------------------------------------------------------- + // Wrap Javadoc options + // ---------------------------------------------------------------------- + + addJavadocOptions( arguments, sourcePaths ); + + // ---------------------------------------------------------------------- + // Wrap Standard doclet Options + // ---------------------------------------------------------------------- + + if ( StringUtils.isEmpty( doclet ) || useStandardDocletOptions ) + { + addStandardDocletOptions( javadocOutputDirectory, arguments ); + } + + // ---------------------------------------------------------------------- + // Write options file and include it in the command line + // ---------------------------------------------------------------------- + + if ( arguments.size() > 0 ) + { + addCommandLineOptions( cmd, arguments, javadocOutputDirectory ); + } + + // ---------------------------------------------------------------------- + // Write packages file and include it in the command line + // ---------------------------------------------------------------------- + + // MJAVADOC-365 if includes/excludes are specified, these take precedence over the default + // package-based mode and force javadoc into file-based mode unless subpackages are + // specified. Subpackages take precedence over file-based include/excludes. Why? Because + // getFiles(...) returns an empty list when subpackages are specified. + boolean includesExcludesActive = + ( sourceFileIncludes != null && !sourceFileIncludes.isEmpty() ) + || ( sourceFileExcludes != null && !sourceFileExcludes.isEmpty() ); + if ( includesExcludesActive && !StringUtils.isEmpty( subpackages ) ) + { + getLog().warn( "sourceFileIncludes and sourceFileExcludes have no effect when subpackages are specified!" ); + includesExcludesActive = false; + } + if ( !packageNames.isEmpty() && !includesExcludesActive ) + { + addCommandLinePackages( cmd, javadocOutputDirectory, packageNames ); + + // ---------------------------------------------------------------------- + // Write argfile file and include it in the command line + // ---------------------------------------------------------------------- + + if ( !filesWithUnnamedPackages.isEmpty() ) + { + addCommandLineArgFile( cmd, javadocOutputDirectory, filesWithUnnamedPackages ); + } + } + else + { + // ---------------------------------------------------------------------- + // Write argfile file and include it in the command line + // ---------------------------------------------------------------------- + + if ( !files.isEmpty() ) + { + addCommandLineArgFile( cmd, javadocOutputDirectory, files ); + } + } + + // ---------------------------------------------------------------------- + // Execute command line + // ---------------------------------------------------------------------- + + executeJavadocCommandLine( cmd, javadocOutputDirectory ); + + // delete generated javadoc files only if no error and no debug mode + // [MJAVADOC-336] Use File.delete() instead of File.deleteOnExit() to + // prevent these files from making their way into archives. + if ( !debug ) + { + for ( int i = 0; i < cmd.getArguments().length; i++ ) + { + String arg = cmd.getArguments()[i].trim(); + + if ( !arg.startsWith( "@" ) ) + { + continue; + } + + File argFile = new File( javadocOutputDirectory, arg.substring( 1 ) ); + if ( argFile.exists() ) + { + argFile.delete(); + } + } + + File scriptFile = new File( javadocOutputDirectory, DEBUG_JAVADOC_SCRIPT_NAME ); + if ( scriptFile.exists() ) + { + scriptFile.delete(); + } + } + if ( applyJavadocSecurityFix ) + { + // finally, patch the Javadoc vulnerability in older Javadoc tools (CVE-2013-1571): + try + { + final int patched = fixFrameInjectionBug( javadocOutputDirectory, getDocencoding() ); + if ( patched > 0 ) + { + getLog().info( + String.format( "Fixed Javadoc frame injection vulnerability (CVE-2013-1571) in %d files.", + patched ) ); + } + } + catch ( IOException e ) + { + throw new MavenReportException( "Failed to patch javadocs vulnerability: " + e.getMessage(), e ); + } + } + else + { + getLog().info( "applying javadoc security fix has been disabled" ); + } + } + + /** + * Method to get the files on the specified source paths + * + * @param sourcePaths a List that contains the paths to the source files + * @return a List that contains the specific path for every source file + * @throws MavenReportException {@link MavenReportException} + */ + protected List<String> getFiles( List<String> sourcePaths ) + throws MavenReportException + { + List<String> files = new ArrayList<String>(); + if ( StringUtils.isEmpty( subpackages ) ) + { + String[] excludedPackages = getExcludedPackages(); + + for ( String sourcePath : sourcePaths ) + { + File sourceDirectory = new File( sourcePath ); + JavadocUtil.addFilesFromSource( files, sourceDirectory, sourceFileIncludes, sourceFileExcludes, + excludedPackages ); + } + } + + return files; + } + + /** + * Method to get the source paths. If no source path is specified in the parameter, the compile source roots + * of the project will be used. + * + * @return a List of the project absolute source paths as <code>String</code> + * @throws MavenReportException {@link MavenReportException} + * @see JavadocUtil#pruneDirs(MavenProject, List) + */ + protected List<String> getSourcePaths() + throws MavenReportException + { + List<String> sourcePaths; + + if ( StringUtils.isEmpty( sourcepath ) ) + { + sourcePaths = new ArrayList<String>( JavadocUtil.pruneDirs( project, getProjectSourceRoots( project ) ) ); + + if ( project.getExecutionProject() != null ) + { + sourcePaths.addAll( JavadocUtil.pruneDirs( project, getExecutionProjectSourceRoots( project ) ) ); + } + + /* + * Should be after the source path (i.e. -sourcepath '.../src/main/java;.../src/main/javadoc') and + * *not* the opposite. If not, the javadoc tool always copies doc files, even if -docfilessubdirs is + * not setted. + */
[... 3818 lines stripped ...]
