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