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