Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
TestJavadocReport |
|
| 2.05;2.05 |
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$ | |
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 | 1 | 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 | 1 | addMainJavadocLink(); |
159 | ||
160 | 1 | super.executeReport( unusedLocale ); |
161 | 1 | } |
162 | ||
163 | @Override | |
164 | public String getName( Locale locale ) | |
165 | { | |
166 | 0 | if ( StringUtils.isEmpty( testName ) ) |
167 | { | |
168 | 0 | return getBundle( locale ).getString( "report.test-javadoc.name" ); |
169 | } | |
170 | ||
171 | 0 | return testName; |
172 | } | |
173 | ||
174 | @Override | |
175 | public String getDescription( Locale locale ) | |
176 | { | |
177 | 0 | if ( StringUtils.isEmpty( testDescription ) ) |
178 | { | |
179 | 0 | return getBundle( locale ).getString( "report.test-javadoc.description" ); |
180 | } | |
181 | ||
182 | 0 | return testDescription; |
183 | } | |
184 | ||
185 | @Override | |
186 | public String getOutputName() | |
187 | { | |
188 | 1 | return destDir + "/index"; |
189 | } | |
190 | ||
191 | @Override | |
192 | public File getReportOutputDirectory() | |
193 | { | |
194 | 2 | if ( reportOutputDirectory == null ) |
195 | { | |
196 | 2 | return outputDirectory; |
197 | } | |
198 | ||
199 | 0 | 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 | 0 | updateReportOutputDirectory( reportOutputDirectory, destDir ); |
211 | 0 | } |
212 | ||
213 | @Override | |
214 | public void setDestDir( String destDir ) | |
215 | { | |
216 | 0 | this.destDir = destDir; |
217 | 0 | updateReportOutputDirectory( reportOutputDirectory, destDir ); |
218 | 0 | } |
219 | ||
220 | private void updateReportOutputDirectory( File reportOutputDirectory, String destDir ) | |
221 | { | |
222 | 0 | if ( reportOutputDirectory != null && destDir != null |
223 | && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) ) | |
224 | { | |
225 | 0 | this.reportOutputDirectory = new File( reportOutputDirectory, destDir ); |
226 | } | |
227 | else | |
228 | { | |
229 | 0 | this.reportOutputDirectory = reportOutputDirectory; |
230 | } | |
231 | 0 | } |
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 | 1 | List<String> dirs = new ArrayList<String>(); |
242 | 1 | if ( StringUtils.isNotEmpty( p.getBuild().getOutputDirectory() ) ) |
243 | { | |
244 | 1 | dirs.add( p.getBuild().getOutputDirectory() ); |
245 | } | |
246 | 1 | if ( StringUtils.isNotEmpty( p.getBuild().getTestOutputDirectory() ) ) |
247 | { | |
248 | 1 | dirs.add( p.getBuild().getTestOutputDirectory() ); |
249 | } | |
250 | ||
251 | 1 | return dirs; |
252 | } | |
253 | ||
254 | @Override | |
255 | protected List<String> getProjectSourceRoots( MavenProject p ) | |
256 | { | |
257 | 1 | if ( "pom".equals( p.getPackaging().toLowerCase() ) ) |
258 | { | |
259 | 0 | return Collections.emptyList(); |
260 | } | |
261 | ||
262 | 1 | 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 | 1 | if ( "pom".equals( p.getExecutionProject().getPackaging().toLowerCase() ) ) |
270 | { | |
271 | 0 | return Collections.emptyList(); |
272 | } | |
273 | ||
274 | 1 | 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 | 1 | return ( p.getTestArtifacts() == null ? Collections.<Artifact>emptyList() |
282 | : new LinkedList<Artifact>( p.getTestArtifacts() ) ); | |
283 | } | |
284 | ||
285 | @Override | |
286 | protected File getJavadocDirectory() | |
287 | { | |
288 | 2 | return testJavadocDirectory; |
289 | } | |
290 | ||
291 | @Override | |
292 | protected String getDoctitle() | |
293 | { | |
294 | 1 | return testDoctitle; |
295 | } | |
296 | ||
297 | @Override | |
298 | protected File getOverview() | |
299 | { | |
300 | 2 | return testOverview; |
301 | } | |
302 | ||
303 | @Override | |
304 | protected String getWindowtitle() | |
305 | { | |
306 | 1 | return testWindowtitle; |
307 | } | |
308 | ||
309 | @Override | |
310 | protected List<Artifact> getCompileArtifacts( ArtifactResolutionResult result ) | |
311 | { | |
312 | 0 | 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 | 0 | 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 | 1 | if ( links == null ) |
332 | { | |
333 | 1 | links = new ArrayList<String>(); |
334 | } | |
335 | ||
336 | // TODO the prerequisite is that the main report is in apidocs | |
337 | 1 | File apidocs = new File( getReportOutputDirectory().getParentFile(), "apidocs" ); |
338 | 1 | if ( apidocs.isDirectory() && !links.contains( "../apidocs" ) ) |
339 | { | |
340 | 1 | links.add( "../apidocs" ); |
341 | } | |
342 | 1 | } |
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 | 0 | return super.configureDependencySourceResolution( config ).withoutCompileSources().withTestSources(); |
353 | } | |
354 | } |