View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.plugins.javadoc;
20  
21  import java.io.File;
22  import java.util.ArrayList;
23  import java.util.Arrays;
24  import java.util.Collections;
25  import java.util.List;
26  
27  import org.apache.maven.artifact.Artifact;
28  import org.apache.maven.plugins.annotations.LifecyclePhase;
29  import org.apache.maven.plugins.annotations.Mojo;
30  import org.apache.maven.plugins.annotations.Parameter;
31  import org.apache.maven.plugins.annotations.ResolutionScope;
32  import org.apache.maven.plugins.javadoc.resolver.SourceResolverConfig;
33  import org.apache.maven.project.MavenProject;
34  import org.codehaus.plexus.util.StringUtils;
35  import org.eclipse.aether.util.filter.ScopeDependencyFilter;
36  
37  /**
38   * Bundles the Javadoc documentation for <code>test Java code</code> in an <b>NON aggregator</b> project into
39   * a jar using the standard <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html">
40   * Javadoc Tool</a>.
41   *
42   * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
43   * @since 2.5
44   */
45  @Mojo(
46          name = "test-jar",
47          defaultPhase = LifecyclePhase.PACKAGE,
48          requiresDependencyResolution = ResolutionScope.TEST,
49          threadSafe = true)
50  public class TestJavadocJar extends JavadocJar {
51      // ----------------------------------------------------------------------
52      // Javadoc Options (should be inline with Javadoc options defined in TestJavadocReport)
53      // ----------------------------------------------------------------------
54  
55      /**
56       * Specifies the destination directory where Javadoc saves the generated HTML files.
57       * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option d</a>.
58       */
59      @Parameter(defaultValue = "${project.build.directory}/testapidocs", required = true)
60      private File outputDirectory;
61  
62      /**
63       * Specifies the Test title to be placed near the top of the overview summary file.
64       * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option doctitle</a>.
65       * @since 2.5
66       */
67      @Parameter(
68              property = "testDoctitle",
69              alias = "doctitle",
70              defaultValue = "${project.name} ${project.version} Test API")
71      private String testDoctitle;
72  
73      /**
74       * Specifies that Javadoc should retrieve the text for the Test overview documentation from the "source" file
75       * specified by path/filename and place it on the Overview page (overview-summary.html).
76       * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option overview</a>.
77       * @since 2.5
78       */
79      @Parameter(
80              property = "testOverview",
81              alias = "overview",
82              defaultValue = "${basedir}/src/test/javadoc/overview.html")
83      private File testOverview;
84  
85      /**
86       * Specifies the Test title to be placed in the HTML title tag.
87       * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html#standard-doclet-options">Doclet option windowtitle</a>.
88       * @since 2.5
89       */
90      @Parameter(
91              property = "testWindowtitle",
92              alias = "windowtitle",
93              defaultValue = "${project.name} ${project.version} Test API")
94      private String testWindowtitle;
95  
96      // ----------------------------------------------------------------------
97      // Mojo Parameters (should be inline with options defined in TestJavadocReport)
98      // ----------------------------------------------------------------------
99  
100     /**
101      * Specifies the Test Javadoc resources directory to be included in the Javadoc (i.e. package.html, images...).
102      *
103      * @since 2.5
104      */
105     @Parameter(alias = "javadocDirectory", defaultValue = "${basedir}/src/test/javadoc")
106     private File testJavadocDirectory;
107 
108     /**
109      * @since 2.10
110      */
111     @Parameter(property = "maven.javadoc.testClassifier", defaultValue = "test-javadoc", required = true)
112     private String testClassifier;
113 
114     // ----------------------------------------------------------------------
115     // Protected methods
116     // ----------------------------------------------------------------------
117 
118     @Override
119     protected String getClassifier() {
120         return testClassifier;
121     }
122 
123     // ----------------------------------------------------------------------
124     // Important Note: should be inline with methods defined in TestJavadocReport
125     // ----------------------------------------------------------------------
126 
127     @Override
128     protected String getOutputDirectory() {
129         return outputDirectory.getAbsoluteFile().toString();
130     }
131 
132     @Override
133     protected File getJavadocDirectory() {
134         return testJavadocDirectory;
135     }
136 
137     @Override
138     protected String getDoctitle() {
139         return testDoctitle;
140     }
141 
142     @Override
143     protected File getOverview() {
144         return testOverview;
145     }
146 
147     @Override
148     protected String getWindowtitle() {
149         return testWindowtitle;
150     }
151 
152     @Override
153     protected List<File> getProjectBuildOutputDirs(MavenProject p) {
154         List<File> dirs = new ArrayList<>();
155         if (StringUtils.isNotEmpty(p.getBuild().getOutputDirectory())) {
156             dirs.add(new File(p.getBuild().getOutputDirectory()));
157         }
158         if (StringUtils.isNotEmpty(p.getBuild().getTestOutputDirectory())) {
159             dirs.add(new File(p.getBuild().getTestOutputDirectory()));
160         }
161 
162         return dirs;
163     }
164 
165     @Override
166     protected List<String> getProjectSourceRoots(MavenProject p) {
167         if ("pom".equals(p.getPackaging().toLowerCase())) {
168             return Collections.emptyList();
169         }
170 
171         return p.getTestCompileSourceRoots();
172     }
173 
174     @Override
175     protected List<String> getExecutionProjectSourceRoots(MavenProject p) {
176         if ("pom".equals(p.getExecutionProject().getPackaging().toLowerCase())) {
177             return Collections.emptyList();
178         }
179 
180         return p.getExecutionProject().getTestCompileSourceRoots();
181     }
182 
183     @Override
184     protected ScopeDependencyFilter getDependencyScopeFilter() {
185         return new ScopeDependencyFilter(
186                 Arrays.asList(
187                         Artifact.SCOPE_COMPILE, Artifact.SCOPE_PROVIDED, Artifact.SCOPE_SYSTEM, Artifact.SCOPE_TEST),
188                 null);
189     }
190 
191     /**
192      * Overriden to enable the resolution of -test-sources jar files.
193      *
194      * {@inheritDoc}
195      */
196     @Override
197     protected SourceResolverConfig configureDependencySourceResolution(final SourceResolverConfig config) {
198         return super.configureDependencySourceResolution(config)
199                 .withoutCompileSources()
200                 .withTestSources();
201     }
202 
203     @Override
204     protected boolean isTest() {
205         return true;
206     }
207 }