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 829400 2012-08-19 17:42:28Z 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://download.oracle.com/javase/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 try
125 {
126 executeReport( locale );
127 }
128 catch ( MavenReportException e )
129 {
130 if ( failOnError )
131 {
132 throw e;
133 }
134 getLog().error( "Error while creating javadoc report: " + e.getMessage(), e );
135 }
136 catch ( RuntimeException e )
137 {
138 if ( failOnError )
139 {
140 throw e;
141 }
142 getLog().error( "Error while creating javadoc report: " + e.getMessage(), e );
143 }
144 }
145
146 /** {@inheritDoc} */
147 public String getOutputName()
148 {
149 return destDir + "/index";
150 }
151
152 /** {@inheritDoc} */
153 public boolean isExternalReport()
154 {
155 return true;
156 }
157
158 /**
159 * {@inheritDoc}
160 *
161 * <br/>
162 * The logic is the following:
163 * <table>
164 * <tbody>
165 * <tr>
166 * <th> isAggregator </th>
167 * <th> hasSourceFiles </th>
168 * <th> isRootProject </th>
169 * <th> Generate Report </th>
170 * </tr>
171 * <tr>
172 * <td>True</td>
173 * <td>True</td>
174 * <td>True</td>
175 * <td>True</td>
176 * </tr>
177 * <tr>
178 * <td>True</td>
179 * <td>True</td>
180 * <td>False</td>
181 * <td>False</td>
182 * </tr>
183 * <tr>
184 * <td>True</td>
185 * <td>False</td>
186 * <td>True</td>
187 * <td>False</td>
188 * </tr>
189 * <tr>
190 * <td>True</td>
191 * <td>False</td>
192 * <td>False</td>
193 * <td>False</td>
194 * </tr>
195 * <tr>
196 * <td>False</td>
197 * <td>True</td>
198 * <td>True</td>
199 * <td>True</td>
200 * </tr>
201 * <tr>
202 * <td>False</td>
203 * <td>True</td>
204 * <td>False</td>
205 * <td>True</td>
206 * </tr>
207 * <tr>
208 * <td>False</td>
209 * <td>False</td>
210 * <td>True</td>
211 * <td>False</td>
212 * </tr>
213 * <tr>
214 * <td>False</td>
215 * <td>False</td>
216 * <td>False</td>
217 * <td>False</td>
218 * </tr>
219 * </tbody>
220 * </table>
221 */
222 public boolean canGenerateReport()
223 {
224 boolean canGenerate = false;
225
226 if ( !this.isAggregator() || ( this.isAggregator() && this.project.isExecutionRoot() ) )
227 {
228 List<String> sourcePaths;
229 List<String> files;
230 try
231 {
232 sourcePaths = getSourcePaths();
233 files = getFiles( sourcePaths );
234 }
235 catch ( MavenReportException e )
236 {
237 getLog().error( e.getMessage(), e );
238 return false;
239 }
240
241 canGenerate = canGenerateReport( files );
242 }
243 if ( getLog().isDebugEnabled() )
244 {
245 getLog().debug( " canGenerateReport " + canGenerate + " project " + this.project );
246 }
247 return canGenerate;
248 }
249
250 /** {@inheritDoc} */
251 public String getCategoryName()
252 {
253 return CATEGORY_PROJECT_REPORTS;
254 }
255
256 /** {@inheritDoc} */
257 public File getReportOutputDirectory()
258 {
259 if ( reportOutputDirectory == null )
260 {
261 return outputDirectory;
262 }
263
264 return reportOutputDirectory;
265 }
266
267 /**
268 * Method to set the directory where the generated reports will be put
269 *
270 * @param reportOutputDirectory the directory file to be set
271 */
272 public void setReportOutputDirectory( File reportOutputDirectory )
273 {
274 updateReportOutputDirectory( reportOutputDirectory, destDir );
275 }
276
277 public void setDestDir( String destDir )
278 {
279 this.destDir = destDir;
280 updateReportOutputDirectory( reportOutputDirectory, destDir );
281 }
282
283 private void updateReportOutputDirectory( File reportOutputDirectory, String destDir )
284 {
285 if ( reportOutputDirectory != null && destDir != null
286 && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) )
287 {
288 this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
289 }
290 else
291 {
292 this.reportOutputDirectory = reportOutputDirectory;
293 }
294 }
295
296 /** {@inheritDoc} */
297 public void execute()
298 throws MojoExecutionException, MojoFailureException
299 {
300 if ( skip )
301 {
302 getLog().info( "Skipping javadoc generation" );
303 return;
304 }
305
306 try
307 {
308 RenderingContext context = new RenderingContext( outputDirectory, getOutputName() + ".html" );
309 SiteRendererSink sink = new SiteRendererSink( context );
310 Locale locale = Locale.getDefault();
311 generate( sink, locale );
312 }
313 catch ( MavenReportException e )
314 {
315 failOnError( "An error has occurred in " + getName( Locale.ENGLISH ) + " report generation", e );
316 }
317 catch ( RuntimeException e )
318 {
319 failOnError( "An error has occurred in " + getName( Locale.ENGLISH ) + " report generation", e );
320 }
321 }
322
323 @Override
324 protected boolean isAggregator()
325 {
326 // only here for backward compatibility, this flag does not work reliably
327 return aggregate;
328 }
329
330 /**
331 * Gets the resource bundle for the specified locale.
332 *
333 * @param locale The locale of the currently generated report.
334 * @return The resource bundle for the requested locale.
335 */
336 private ResourceBundle getBundle( Locale locale )
337 {
338 return ResourceBundle.getBundle( "javadoc-report", locale, getClass().getClassLoader() );
339 }
340 }