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