1 package org.apache.maven.plugin.javadoc;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.io.File;
23 import java.util.ArrayList;
24 import java.util.Collections;
25 import java.util.LinkedList;
26 import java.util.List;
27 import java.util.Locale;
28 import java.util.ResourceBundle;
29
30 import org.apache.maven.artifact.Artifact;
31 import org.apache.maven.artifact.resolver.ArtifactResolutionResult;
32 import org.apache.maven.plugin.javadoc.resolver.SourceResolverConfig;
33 import org.apache.maven.project.MavenProject;
34 import org.apache.maven.reporting.MavenReportException;
35 import org.codehaus.plexus.util.StringUtils;
36
37 /**
38 * Generates documentation for the <code>Java Test code</code> in an <b>NON aggregator</b> project using the standard
39 * <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a>.
40 *
41 * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
42 * @version $Id: TestJavadocReport.html 829400 2012-08-19 17:42:28Z hboutemy $
43 * @since 2.3
44 * @goal test-javadoc
45 * @execute phase=generate-test-sources
46 * @requiresDependencyResolution test
47 * @see <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a>
48 * @see <a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#options">Javadoc Options </a>
49 */
50 public class TestJavadocReport
51 extends JavadocReport
52 {
53 // ----------------------------------------------------------------------
54 // Javadoc Options (should be inline with options defined in TestJavadocJar)
55 // ----------------------------------------------------------------------
56
57 /**
58 * Specifies the Test title to be placed near the top of the overview summary file.
59 * <br/>
60 * See <a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#doctitle">doctitle</a>.
61 * <br/>
62 *
63 * @parameter expression="${testDoctitle}" alias="doctitle"
64 * default-value="${project.name} ${project.version} Test API"
65 * @since 2.5
66 */
67 private String testDoctitle;
68
69 /**
70 * Specifies that Javadoc should retrieve the text for the Test overview documentation from the "source" file
71 * specified by path/filename and place it on the Overview page (overview-summary.html).
72 * <br/>
73 * <b>Note</b>: could be in conflict with <nooverview/>.
74 * <br/>
75 * See <a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#overview">overview</a>.
76 * <br/>
77 *
78 * @parameter expression="${testOverview}" alias="overview"
79 * default-value="${basedir}/src/test/javadoc/overview.html"
80 * @since 2.5
81 */
82 private File testOverview;
83
84 /**
85 * Specifies the Test title to be placed in the HTML title tag.
86 * <br/>
87 * See <a href="http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#windowtitle">windowtitle</a>.
88 * <br/>
89 *
90 * @parameter expression="${testWindowtitle}" alias="windowtitle"
91 * default-value="${project.name} ${project.version} Test API"
92 * @since 2.5
93 */
94 private String testWindowtitle;
95
96 // ----------------------------------------------------------------------
97 // Mojo Parameters (should be inline with options defined in TestJavadocJar)
98 // ----------------------------------------------------------------------
99
100 /**
101 * Specifies the destination directory where test Javadoc saves the generated HTML files.
102 *
103 * @parameter expression="${reportTestOutputDirectory}" default-value="${project.reporting.outputDirectory}/testapidocs"
104 * @required
105 */
106 private File reportOutputDirectory;
107
108 /**
109 * The name of the destination directory.
110 * <br/>
111 *
112 * @parameter expression="${destDir}" default-value="testapidocs"
113 */
114 private String destDir;
115
116 /**
117 * Specifies the Test Javadoc resources directory to be included in the Javadoc (i.e. package.html, images...).
118 * <br/>
119 * Could be used in addition of <code>docfilessubdirs</code> parameter.
120 * <br/>
121 * See <a href="#docfilessubdirs">docfilessubdirs</a>.
122 *
123 * @parameter expression="${basedir}/src/test/javadoc" alias="javadocDirectory"
124 * @since 2.5
125 */
126 private File testJavadocDirectory;
127
128 // ----------------------------------------------------------------------
129 // Report Mojo Parameters
130 // ----------------------------------------------------------------------
131
132 /**
133 * The name of the Test Javadoc report to be displayed in the Maven Generated Reports page
134 * (i.e. <code>project-reports.html</code>).
135 *
136 * @parameter expression="${testName}" alias="name"
137 * @since 2.5
138 */
139 private String testName;
140
141 /**
142 * The description of the Test Javadoc report to be displayed in the Maven Generated Reports page
143 * (i.e. <code>project-reports.html</code>).
144 *
145 * @parameter expression="${testDescription}" alias="description"
146 * @since 2.5
147 */
148 private String testDescription;
149
150 // ----------------------------------------------------------------------
151 // Report public methods
152 // ----------------------------------------------------------------------
153
154 @Override
155 protected void executeReport( Locale unusedLocale )
156 throws MavenReportException
157 {
158 addMainJavadocLink();
159
160 super.executeReport( unusedLocale );
161 }
162
163 @Override
164 public String getName( Locale locale )
165 {
166 if ( StringUtils.isEmpty( testName ) )
167 {
168 return getBundle( locale ).getString( "report.test-javadoc.name" );
169 }
170
171 return testName;
172 }
173
174 @Override
175 public String getDescription( Locale locale )
176 {
177 if ( StringUtils.isEmpty( testDescription ) )
178 {
179 return getBundle( locale ).getString( "report.test-javadoc.description" );
180 }
181
182 return testDescription;
183 }
184
185 @Override
186 public String getOutputName()
187 {
188 return destDir + "/index";
189 }
190
191 @Override
192 public File getReportOutputDirectory()
193 {
194 if ( reportOutputDirectory == null )
195 {
196 return outputDirectory;
197 }
198
199 return reportOutputDirectory;
200 }
201
202 /**
203 * Method to set the directory where the generated reports will be put
204 *
205 * @param reportOutputDirectory the directory file to be set
206 */
207 @Override
208 public void setReportOutputDirectory( File reportOutputDirectory )
209 {
210 updateReportOutputDirectory( reportOutputDirectory, destDir );
211 }
212
213 @Override
214 public void setDestDir( String destDir )
215 {
216 this.destDir = destDir;
217 updateReportOutputDirectory( reportOutputDirectory, destDir );
218 }
219
220 private void updateReportOutputDirectory( File reportOutputDirectory, String destDir )
221 {
222 if ( reportOutputDirectory != null && destDir != null
223 && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) )
224 {
225 this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
226 }
227 else
228 {
229 this.reportOutputDirectory = reportOutputDirectory;
230 }
231 }
232
233 // ----------------------------------------------------------------------
234 // Protected methods
235 // Important Note: should be inline with methods defined in TestJavadocJar
236 // ----------------------------------------------------------------------
237
238 @Override
239 protected List<String> getProjectBuildOutputDirs( MavenProject p )
240 {
241 List<String> dirs = new ArrayList<String>();
242 if ( StringUtils.isNotEmpty( p.getBuild().getOutputDirectory() ) )
243 {
244 dirs.add( p.getBuild().getOutputDirectory() );
245 }
246 if ( StringUtils.isNotEmpty( p.getBuild().getTestOutputDirectory() ) )
247 {
248 dirs.add( p.getBuild().getTestOutputDirectory() );
249 }
250
251 return dirs;
252 }
253
254 @Override
255 protected List<String> getProjectSourceRoots( MavenProject p )
256 {
257 if ( "pom".equals( p.getPackaging().toLowerCase() ) )
258 {
259 return Collections.emptyList();
260 }
261
262 return ( p.getTestCompileSourceRoots() == null ? Collections.<String>emptyList()
263 : new LinkedList<String>( p.getTestCompileSourceRoots() ) );
264 }
265
266 @Override
267 protected List<String> getExecutionProjectSourceRoots( MavenProject p )
268 {
269 if ( "pom".equals( p.getExecutionProject().getPackaging().toLowerCase() ) )
270 {
271 return Collections.emptyList();
272 }
273
274 return ( p.getExecutionProject().getTestCompileSourceRoots() == null ? Collections.<String>emptyList()
275 : new LinkedList<String>( p.getExecutionProject().getTestCompileSourceRoots() ) );
276 }
277
278 @Override
279 protected List<Artifact> getProjectArtifacts( MavenProject p )
280 {
281 return ( p.getTestArtifacts() == null ? Collections.<Artifact>emptyList()
282 : new LinkedList<Artifact>( p.getTestArtifacts() ) );
283 }
284
285 @Override
286 protected File getJavadocDirectory()
287 {
288 return testJavadocDirectory;
289 }
290
291 @Override
292 protected String getDoctitle()
293 {
294 return testDoctitle;
295 }
296
297 @Override
298 protected File getOverview()
299 {
300 return testOverview;
301 }
302
303 @Override
304 protected String getWindowtitle()
305 {
306 return testWindowtitle;
307 }
308
309 @Override
310 protected List<Artifact> getCompileArtifacts( ArtifactResolutionResult result )
311 {
312 return JavadocUtil.getCompileArtifacts( result.getArtifacts(), true );
313 }
314
315 /**
316 * Gets the resource bundle for the specified locale.
317 *
318 * @param locale The locale of the currently generated report.
319 * @return The resource bundle for the requested locale.
320 */
321 private ResourceBundle getBundle( Locale locale )
322 {
323 return ResourceBundle.getBundle( "test-javadoc-report", locale, getClass().getClassLoader() );
324 }
325
326 /**
327 * Add the <code>../apidocs</code> to the links parameter so Test report could be linked to the Main report.
328 */
329 private void addMainJavadocLink()
330 {
331 if ( links == null )
332 {
333 links = new ArrayList<String>();
334 }
335
336 // TODO the prerequisite is that the main report is in apidocs
337 File apidocs = new File( getReportOutputDirectory().getParentFile(), "apidocs" );
338 if ( apidocs.isDirectory() && !links.contains( "../apidocs" ) )
339 {
340 links.add( "../apidocs" );
341 }
342 }
343
344 /**
345 * Overridden to enable the resolution of -test-sources jar files.
346 *
347 * {@inheritDoc}
348 */
349 @Override
350 protected SourceResolverConfig configureDependencySourceResolution( final SourceResolverConfig config )
351 {
352 return super.configureDependencySourceResolution( config ).withoutCompileSources().withTestSources();
353 }
354 }