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 }