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$
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="${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.
76 *
77 * @since 2.1
78 * @parameter expression="${name}"
79 */
80 private String name;
81
82 /**
83 * The description of the Javadoc report.
84 *
85 * @since 2.1
86 * @parameter expression="${description}"
87 */
88 private String description;
89
90 // ----------------------------------------------------------------------
91 // Report public methods
92 // ----------------------------------------------------------------------
93
94 /** {@inheritDoc} */
95 public String getName( Locale locale )
96 {
97 if ( StringUtils.isEmpty( name ) )
98 {
99 return getBundle( locale ).getString( "report.javadoc.name" );
100 }
101
102 return name;
103 }
104
105 /** {@inheritDoc} */
106 public String getDescription( Locale locale )
107 {
108 if ( StringUtils.isEmpty( description ) )
109 {
110 return getBundle( locale ).getString( "report.javadoc.description" );
111 }
112
113 return description;
114 }
115
116 /** {@inheritDoc} */
117 public void generate( Sink sink, Locale locale )
118 throws MavenReportException
119 {
120 outputDirectory = getReportOutputDirectory();
121
122 executeReport( locale );
123 }
124
125 /** {@inheritDoc} */
126 public String getOutputName()
127 {
128 return destDir + "/index";
129 }
130
131 /** {@inheritDoc} */
132 public boolean isExternalReport()
133 {
134 return true;
135 }
136
137 /**
138 * {@inheritDoc}
139 *
140 * <br/>
141 * The logic is the following:
142 * <table>
143 * <tbody>
144 * <tr>
145 * <th> isAggregator </th>
146 * <th> hasSourceFiles </th>
147 * <th> isRootProject </th>
148 * <th> Generate Report </th>
149 * </tr>
150 * <tr>
151 * <td>True</td>
152 * <td>True</td>
153 * <td>True</td>
154 * <td>True</td>
155 * </tr>
156 * <tr>
157 * <td>True</td>
158 * <td>True</td>
159 * <td>False</td>
160 * <td>False</td>
161 * </tr>
162 * <tr>
163 * <td>True</td>
164 * <td>False</td>
165 * <td>True</td>
166 * <td>False</td>
167 * </tr>
168 * <tr>
169 * <td>True</td>
170 * <td>False</td>
171 * <td>False</td>
172 * <td>False</td>
173 * </tr>
174 * <tr>
175 * <td>False</td>
176 * <td>True</td>
177 * <td>True</td>
178 * <td>True</td>
179 * </tr>
180 * <tr>
181 * <td>False</td>
182 * <td>True</td>
183 * <td>False</td>
184 * <td>True</td>
185 * </tr>
186 * <tr>
187 * <td>False</td>
188 * <td>False</td>
189 * <td>True</td>
190 * <td>False</td>
191 * </tr>
192 * <tr>
193 * <td>False</td>
194 * <td>False</td>
195 * <td>False</td>
196 * <td>False</td>
197 * </tr>
198 * </tbody>
199 * </table>
200 */
201 public boolean canGenerateReport()
202 {
203 boolean canGenerate = false;
204
205 if ( !this.isAggregator() || ( this.isAggregator() && this.project.isExecutionRoot() ) )
206 {
207 List sourcePaths = getSourcePaths();
208
209 List files = getFiles( sourcePaths );
210
211 canGenerate = canGenerateReport( files );
212 }
213 return canGenerate;
214 }
215
216 /** {@inheritDoc} */
217 public String getCategoryName()
218 {
219 return CATEGORY_PROJECT_REPORTS;
220 }
221
222 /** {@inheritDoc} */
223 public File getReportOutputDirectory()
224 {
225 if ( reportOutputDirectory == null )
226 {
227 return outputDirectory;
228 }
229
230 return reportOutputDirectory;
231 }
232
233 /**
234 * Method to set the directory where the generated reports will be put
235 *
236 * @param reportOutputDirectory the directory file to be set
237 */
238 public void setReportOutputDirectory( File reportOutputDirectory )
239 {
240 if ( ( reportOutputDirectory != null ) && ( !reportOutputDirectory.getAbsolutePath().endsWith( destDir ) ) )
241 {
242 this.reportOutputDirectory = new File( reportOutputDirectory, destDir );
243 }
244 else
245 {
246 this.reportOutputDirectory = reportOutputDirectory;
247 }
248 }
249
250 /** {@inheritDoc} */
251 public void execute()
252 throws MojoExecutionException, MojoFailureException
253 {
254 if ( skip )
255 {
256 getLog().info( "Skipping javadoc generation" );
257 return;
258 }
259
260 try
261 {
262 RenderingContext context = new RenderingContext( outputDirectory, getOutputName() + ".html" );
263 SiteRendererSink sink = new SiteRendererSink( context );
264 Locale locale = Locale.getDefault();
265 generate( sink, locale );
266 }
267 catch ( MavenReportException e )
268 {
269 if ( failOnError )
270 {
271 throw new MojoExecutionException( "An error has occurred in " + getName( Locale.ENGLISH )
272 + " report generation:" + e.getMessage(), e );
273 }
274
275 getLog().error( "An error has occurred in " + getName( Locale.ENGLISH )
276 + " report generation:" + e.getMessage(), e );
277 }
278 catch ( RuntimeException e )
279 {
280 if ( failOnError )
281 {
282 throw e;
283 }
284
285 getLog().error( e.getMessage(), e );
286 }
287 }
288
289 /** {@inheritDoc} */
290 protected boolean isAggregator()
291 {
292 // only here for backward compatibility, this flag does not work reliably
293 return aggregate;
294 }
295
296 /**
297 * Gets the resource bundle for the specified locale.
298 *
299 * @param locale The locale of the currently generated report.
300 * @return The resource bundle for the requested locale.
301 */
302 private ResourceBundle getBundle( Locale locale )
303 {
304 return ResourceBundle.getBundle( "javadoc-report", locale, getClass().getClassLoader() );
305 }
306 }