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 java.io.File;
23  import java.util.List;
24  import java.util.Locale;
25  import java.util.ResourceBundle;
26  
27  import org.apache.maven.doxia.module.xhtml.decoration.render.RenderingContext;
28  import org.apache.maven.doxia.siterenderer.sink.SiteRendererSink;
29  import org.apache.maven.plugin.MojoExecutionException;
30  import org.apache.maven.plugin.MojoFailureException;
31  import org.apache.maven.reporting.MavenReport;
32  import org.apache.maven.reporting.MavenReportException;
33  import org.codehaus.doxia.sink.Sink;
34  import org.codehaus.plexus.util.StringUtils;
35  
36  /**
37   * Generates documentation for the <code>Java code</code> in an <b>NON aggregator</b> project using the standard
38   * <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a>.
39   *
40   * @author <a href="mailto:evenisse@apache.org">Emmanuel Venisse</a>
41   * @author <a href="mailto:vincent.siveton@gmail.com">Vincent Siveton</a>
42   * @version $Id: JavadocReport.html 829394 2012-08-19 17:31:42Z hboutemy $
43   * @since 2.0
44   * @goal javadoc
45   * @execute phase="generate-sources"
46   * @see <a href="http://java.sun.com/j2se/javadoc/">Javadoc Tool</a>
47   * @see <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#options">Javadoc Options</a>
48   */
49  public class JavadocReport
50      extends AbstractJavadocMojo
51      implements MavenReport
52  {
53      // ----------------------------------------------------------------------
54      // Report Mojo Parameters
55      // ----------------------------------------------------------------------
56  
57      /**
58       * Specifies the destination directory where javadoc saves the generated HTML files.
59       *
60       * @parameter expression="${reportOutputDirectory}" default-value="${project.reporting.outputDirectory}/apidocs"
61       * @required
62       */
63      private File reportOutputDirectory;
64  
65      /**
66       * The name of the destination directory.
67       * <br/>
68       *
69       * @since 2.1
70       * @parameter expression="${destDir}" default-value="apidocs"
71       */
72      private String destDir;
73  
74      /**
75       * The name of the Javadoc report to be displayed in the Maven Generated Reports page
76       * (i.e. <code>project-reports.html</code>).
77       *
78       * @since 2.1
79       * @parameter expression="${name}"
80       */
81      private String name;
82  
83      /**
84       * The description of the Javadoc report to be displayed in the Maven Generated Reports page
85       * (i.e. <code>project-reports.html</code>).
86       *
87       * @since 2.1
88       * @parameter expression="${description}"
89       */
90      private String description;
91  
92      // ----------------------------------------------------------------------
93      // Report public methods
94      // ----------------------------------------------------------------------
95  
96      /** {@inheritDoc} */
97      public String getName( Locale locale )
98      {
99          if ( StringUtils.isEmpty( name ) )
100         {
101             return getBundle( locale ).getString( "report.javadoc.name" );
102         }
103 
104         return name;
105     }
106 
107     /** {@inheritDoc} */
108     public String getDescription( Locale locale )
109     {
110         if ( StringUtils.isEmpty( description ) )
111         {
112             return getBundle( locale ).getString( "report.javadoc.description" );
113         }
114 
115         return description;
116     }
117 
118     /** {@inheritDoc} */
119     public void generate( Sink sink, Locale locale )
120         throws MavenReportException
121     {
122         outputDirectory = getReportOutputDirectory();
123 
124         executeReport( locale );
125     }
126 
127     /** {@inheritDoc} */
128     public String getOutputName()
129     {
130         return destDir + "/index";
131     }
132 
133     /** {@inheritDoc} */
134     public boolean isExternalReport()
135     {
136         return true;
137     }
138 
139     /**
140      * {@inheritDoc}
141      *
142      * <br/>
143      * The logic is the following:
144      * <table>
145      *   <tbody>
146      *     <tr>
147      *       <th> isAggregator </th>
148      *       <th> hasSourceFiles </th>
149      *       <th> isRootProject </th>
150      *       <th> Generate Report </th>
151      *     </tr>
152      *     <tr>
153      *       <td>True</td>
154      *       <td>True</td>
155      *       <td>True</td>
156      *       <td>True</td>
157      *     </tr>
158      *     <tr>
159      *       <td>True</td>
160      *       <td>True</td>
161      *       <td>False</td>
162      *       <td>False</td>
163      *     </tr>
164      *     <tr>
165      *       <td>True</td>
166      *       <td>False</td>
167      *       <td>True</td>
168      *       <td>False</td>
169      *     </tr>
170      *     <tr>
171      *       <td>True</td>
172      *       <td>False</td>
173      *       <td>False</td>
174      *       <td>False</td>
175      *     </tr>
176      *     <tr>
177      *       <td>False</td>
178      *       <td>True</td>
179      *       <td>True</td>
180      *       <td>True</td>
181      *     </tr>
182      *     <tr>
183      *       <td>False</td>
184      *       <td>True</td>
185      *       <td>False</td>
186      *       <td>True</td>
187      *     </tr>
188      *     <tr>
189      *        <td>False</td>
190      *        <td>False</td>
191      *        <td>True</td>
192      *        <td>False</td>
193      *      </tr>
194      *      <tr>
195      *        <td>False</td>
196      *        <td>False</td>
197      *        <td>False</td>
198      *        <td>False</td>
199      *      </tr>
200      *    </tbody>
201      *  </table>
202      */
203     public boolean canGenerateReport()
204     {
205         boolean canGenerate = false;
206 
207         if ( !this.isAggregator() || ( this.isAggregator() && this.project.isExecutionRoot() ) )
208         {
209             List sourcePaths = getSourcePaths();
210 
211             List files = getFiles( sourcePaths );
212 
213             canGenerate = canGenerateReport( files );
214         }
215         if ( getLog().isDebugEnabled() )
216         {
217             getLog().debug( " canGenerateReport " + canGenerate + " project " + this.project );
218         }
219         return canGenerate;
220     }
221 
222     /** {@inheritDoc} */
223     public String getCategoryName()
224     {
225         return CATEGORY_PROJECT_REPORTS;
226     }
227 
228     /** {@inheritDoc} */
229     public File getReportOutputDirectory()
230     {
231         if ( reportOutputDirectory == null )
232         {
233             return outputDirectory;
234         }
235 
236         return reportOutputDirectory;
237     }
238 
239     /**
240      * Method to set the directory where the generated reports will be put
241      *
242      * @param reportOutputDirectory the directory file to be set
243      */
244     public void setReportOutputDirectory( File reportOutputDirectory )
245     {
246         updateReportOutputDirectory( reportOutputDirectory, destDir );
247     }
248 
249     public void setDestDir( String destDir )
250     {
251         this.destDir = destDir;
252         updateReportOutputDirectory( reportOutputDirectory, destDir );
253     }
254 
255     private void updateReportOutputDirectory( File reportOutputDirectory, String destDir )
256     {
257         if ( reportOutputDirectory != null && destDir != null
258              && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) )
259         {
260             this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
261         }
262         else
263         {
264             this.reportOutputDirectory = reportOutputDirectory;
265         }
266     }
267 
268     /** {@inheritDoc} */
269     public void execute()
270         throws MojoExecutionException, MojoFailureException
271     {
272         if ( skip )
273         {
274             getLog().info( "Skipping javadoc generation" );
275             return;
276         }
277 
278         try
279         {
280             RenderingContext context = new RenderingContext( outputDirectory, getOutputName() + ".html" );
281             SiteRendererSink sink = new SiteRendererSink( context );
282             Locale locale = Locale.getDefault();
283             generate( sink, locale );
284         }
285         catch ( MavenReportException e )
286         {
287             if ( failOnError )
288             {
289                 throw new MojoExecutionException( "An error has occurred in " + getName( Locale.ENGLISH )
290                     + " report generation:" + e.getMessage(), e );
291             }
292 
293             getLog().error( "An error has occurred in " + getName( Locale.ENGLISH )
294                     + " report generation:" + e.getMessage(), e );
295         }
296         catch ( RuntimeException e )
297         {
298             if ( failOnError )
299             {
300                 throw e;
301             }
302 
303             getLog().error( e.getMessage(), e );
304         }
305     }
306 
307     /** {@inheritDoc} */
308     protected boolean isAggregator()
309     {
310         // only here for backward compatibility, this flag does not work reliably
311         return aggregate;
312     }
313 
314     /**
315      * Gets the resource bundle for the specified locale.
316      *
317      * @param locale The locale of the currently generated report.
318      * @return The resource bundle for the requested locale.
319      */
320     private ResourceBundle getBundle( Locale locale )
321     {
322         return ResourceBundle.getBundle( "javadoc-report", locale, getClass().getClassLoader() );
323     }
324 }