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 867202 2013-06-24 11:56:53Z olamy $
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/1.4.2/docs/tooldocs/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/1.4.2/docs/tooldocs/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/1.4.2/docs/tooldocs/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 <a href="http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#windowtitle">windowtitle</a>.
92       * <br/>
93       *
94       * @since 2.5
95       */
96      @Parameter( property = "testWindowtitle", alias = "windowtitle",
97                  defaultValue = "${project.name} ${project.version} Test API" )
98      private String testWindowtitle;
99  
100     // ----------------------------------------------------------------------
101     // Mojo Parameters (should be inline with options defined in TestJavadocJar)
102     // ----------------------------------------------------------------------
103 
104     /**
105      * Specifies the destination directory where test Javadoc saves the generated HTML files.
106      */
107     @Parameter( property = "reportTestOutputDirectory",
108                 defaultValue = "${project.reporting.outputDirectory}/testapidocs", required = true )
109     private File reportOutputDirectory;
110 
111     /**
112      * The name of the destination directory.
113      * <br/>
114      */
115     @Parameter( property = "destDir", defaultValue = "testapidocs" )
116     private String destDir;
117 
118     /**
119      * Specifies the Test Javadoc resources directory to be included in the Javadoc (i.e. package.html, images...).
120      * <br/>
121      * Could be used in addition of <code>docfilessubdirs</code> parameter.
122      * <br/>
123      * See <a href="#docfilessubdirs">docfilessubdirs</a>.
124      *
125      * @since 2.5
126      */
127     @Parameter( alias = "javadocDirectory", defaultValue = "${basedir}/src/test/javadoc" )
128     private File testJavadocDirectory;
129 
130     // ----------------------------------------------------------------------
131     // Report Mojo Parameters
132     // ----------------------------------------------------------------------
133 
134     /**
135      * The name of the Test Javadoc report to be displayed in the Maven Generated Reports page
136      * (i.e. <code>project-reports.html</code>).
137      *
138      * @since 2.5
139      */
140     @Parameter( property = "testName", alias = "name" )
141     private String testName;
142 
143     /**
144      * The description of the Test Javadoc report to be displayed in the Maven Generated Reports page
145      * (i.e. <code>project-reports.html</code>).
146      *
147      * @since 2.5
148      */
149     @Parameter( property = "testDescription", alias = "description" )
150     private String testDescription;
151 
152     // ----------------------------------------------------------------------
153     // Report public methods
154     // ----------------------------------------------------------------------
155 
156     @Override
157     protected void executeReport( Locale unusedLocale )
158         throws MavenReportException
159     {
160         addMainJavadocLink();
161 
162         super.executeReport( unusedLocale );
163     }
164 
165     @Override
166     public String getName( Locale locale )
167     {
168         if ( StringUtils.isEmpty( testName ) )
169         {
170             return getBundle( locale ).getString( "report.test-javadoc.name" );
171         }
172 
173         return testName;
174     }
175 
176     @Override
177     public String getDescription( Locale locale )
178     {
179         if ( StringUtils.isEmpty( testDescription ) )
180         {
181             return getBundle( locale ).getString( "report.test-javadoc.description" );
182         }
183 
184         return testDescription;
185     }
186 
187     @Override
188     public String getOutputName()
189     {
190         return destDir + "/index";
191     }
192 
193     @Override
194     public File getReportOutputDirectory()
195     {
196         if ( reportOutputDirectory == null )
197         {
198             return outputDirectory;
199         }
200 
201         return reportOutputDirectory;
202     }
203 
204     /**
205      * Method to set the directory where the generated reports will be put
206      *
207      * @param reportOutputDirectory the directory file to be set
208      */
209     @Override
210     public void setReportOutputDirectory( File reportOutputDirectory )
211     {
212         updateReportOutputDirectory( reportOutputDirectory, destDir );
213     }
214 
215     @Override
216     public void setDestDir( String destDir )
217     {
218         this.destDir = destDir;
219         updateReportOutputDirectory( reportOutputDirectory, destDir );
220     }
221 
222     private void updateReportOutputDirectory( File reportOutputDirectory, String destDir )
223     {
224         if ( reportOutputDirectory != null && destDir != null
225              && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) )
226         {
227             this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
228         }
229         else
230         {
231             this.reportOutputDirectory = reportOutputDirectory;
232         }
233     }
234 
235     // ----------------------------------------------------------------------
236     // Protected methods
237     // Important Note: should be inline with methods defined in TestJavadocJar
238     // ----------------------------------------------------------------------
239 
240     @Override
241     protected List<String> getProjectBuildOutputDirs( MavenProject p )
242     {
243         List<String> dirs = new ArrayList<String>();
244         if ( StringUtils.isNotEmpty( p.getBuild().getOutputDirectory() ) )
245         {
246             dirs.add( p.getBuild().getOutputDirectory() );
247         }
248         if ( StringUtils.isNotEmpty( p.getBuild().getTestOutputDirectory() ) )
249         {
250             dirs.add( p.getBuild().getTestOutputDirectory() );
251         }
252 
253         return dirs;
254     }
255 
256     @Override
257     protected List<String> getProjectSourceRoots( MavenProject p )
258     {
259         if ( "pom".equals( p.getPackaging().toLowerCase() ) )
260         {
261             return Collections.emptyList();
262         }
263 
264         return ( p.getTestCompileSourceRoots() == null ? Collections.<String>emptyList()
265                         : new LinkedList<String>( p.getTestCompileSourceRoots() ) );
266     }
267 
268     @Override
269     protected List<String> getExecutionProjectSourceRoots( MavenProject p )
270     {
271         if ( "pom".equals( p.getExecutionProject().getPackaging().toLowerCase() ) )
272         {
273             return Collections.emptyList();
274         }
275 
276         return ( p.getExecutionProject().getTestCompileSourceRoots() == null ? Collections.<String>emptyList()
277                         : new LinkedList<String>( p.getExecutionProject().getTestCompileSourceRoots() ) );
278     }
279 
280     @Override
281     protected List<Artifact> getProjectArtifacts( MavenProject p )
282     {
283         return ( p.getTestArtifacts() == null ? Collections.<Artifact>emptyList()
284                         : new LinkedList<Artifact>( p.getTestArtifacts() ) );
285     }
286 
287     @Override
288     protected File getJavadocDirectory()
289     {
290         return testJavadocDirectory;
291     }
292 
293     @Override
294     protected String getDoctitle()
295     {
296         return testDoctitle;
297     }
298 
299     @Override
300     protected File getOverview()
301     {
302         return testOverview;
303     }
304 
305     @Override
306     protected String getWindowtitle()
307     {
308         return testWindowtitle;
309     }
310 
311     @Override
312     protected List<Artifact> getCompileArtifacts( ArtifactResolutionResult result )
313     {
314         return JavadocUtil.getCompileArtifacts( result.getArtifacts(), true );
315     }
316 
317     /**
318      * Gets the resource bundle for the specified locale.
319      *
320      * @param locale The locale of the currently generated report.
321      * @return The resource bundle for the requested locale.
322      */
323     private ResourceBundle getBundle( Locale locale )
324     {
325         return ResourceBundle.getBundle( "test-javadoc-report", locale, getClass().getClassLoader() );
326     }
327 
328     /**
329      * Add the <code>../apidocs</code> to the links parameter so Test report could be linked to the Main report.
330      */
331     private void addMainJavadocLink()
332     {
333         if ( links == null )
334         {
335             links = new ArrayList<String>();
336         }
337 
338         // TODO the prerequisite is that the main report is in apidocs
339         File apidocs = new File( getReportOutputDirectory().getParentFile(), "apidocs" );
340         if ( apidocs.isDirectory() && !links.contains( "../apidocs" ) )
341         {
342             links.add( "../apidocs" );
343         }
344     }
345     
346     /**
347      * Overridden to enable the resolution of -test-sources jar files.
348      * 
349      * {@inheritDoc}
350      */
351     @Override
352     protected SourceResolverConfig configureDependencySourceResolution( final SourceResolverConfig config )
353     {
354         return super.configureDependencySourceResolution( config ).withoutCompileSources().withTestSources();
355     }
356 }