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