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 829396 2012-08-19 17:35:19Z 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;
210 List files;
211 try
212 {
213 sourcePaths = getSourcePaths();
214 files = getFiles( sourcePaths );
215 }
216 catch ( MavenReportException e )
217 {
218 getLog().error( e.getMessage(), e );
219 return false;
220 }
221
222 canGenerate = canGenerateReport( files );
223 }
224 if ( getLog().isDebugEnabled() )
225 {
226 getLog().debug( " canGenerateReport " + canGenerate + " project " + this.project );
227 }
228 return canGenerate;
229 }
230
231 /** {@inheritDoc} */
232 public String getCategoryName()
233 {
234 return CATEGORY_PROJECT_REPORTS;
235 }
236
237 /** {@inheritDoc} */
238 public File getReportOutputDirectory()
239 {
240 if ( reportOutputDirectory == null )
241 {
242 return outputDirectory;
243 }
244
245 return reportOutputDirectory;
246 }
247
248 /**
249 * Method to set the directory where the generated reports will be put
250 *
251 * @param reportOutputDirectory the directory file to be set
252 */
253 public void setReportOutputDirectory( File reportOutputDirectory )
254 {
255 updateReportOutputDirectory( reportOutputDirectory, destDir );
256 }
257
258 public void setDestDir( String destDir )
259 {
260 this.destDir = destDir;
261 updateReportOutputDirectory( reportOutputDirectory, destDir );
262 }
263
264 private void updateReportOutputDirectory( File reportOutputDirectory, String destDir )
265 {
266 if ( reportOutputDirectory != null && destDir != null
267 && !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) )
268 {
269 this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
270 }
271 else
272 {
273 this.reportOutputDirectory = reportOutputDirectory;
274 }
275 }
276
277 /** {@inheritDoc} */
278 public void execute()
279 throws MojoExecutionException, MojoFailureException
280 {
281 if ( skip )
282 {
283 getLog().info( "Skipping javadoc generation" );
284 return;
285 }
286
287 try
288 {
289 RenderingContext context = new RenderingContext( outputDirectory, getOutputName() + ".html" );
290 SiteRendererSink sink = new SiteRendererSink( context );
291 Locale locale = Locale.getDefault();
292 generate( sink, locale );
293 }
294 catch ( MavenReportException e )
295 {
296 if ( failOnError )
297 {
298 throw new MojoExecutionException( "An error has occurred in " + getName( Locale.ENGLISH )
299 + " report generation:" + e.getMessage(), e );
300 }
301
302 getLog().error( "An error has occurred in " + getName( Locale.ENGLISH )
303 + " report generation:" + e.getMessage(), e );
304 }
305 catch ( RuntimeException e )
306 {
307 if ( failOnError )
308 {
309 throw e;
310 }
311
312 getLog().error( e.getMessage(), e );
313 }
314 }
315
316 /** {@inheritDoc} */
317 protected boolean isAggregator()
318 {
319 // only here for backward compatibility, this flag does not work reliably
320 return aggregate;
321 }
322
323 /**
324 * Gets the resource bundle for the specified locale.
325 *
326 * @param locale The locale of the currently generated report.
327 * @return The resource bundle for the requested locale.
328 */
329 private ResourceBundle getBundle( Locale locale )
330 {
331 return ResourceBundle.getBundle( "javadoc-report", locale, getClass().getClassLoader() );
332 }
333 }