1 /*
2 * Copyright 2009-2012 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.maven.apidoc;
17
18 import java.io.File;
19 import java.io.FileWriter;
20 import java.io.IOException;
21 import java.io.Writer;
22 import java.util.HashMap;
23 import java.util.Locale;
24 import java.util.Map;
25 import java.util.ResourceBundle;
26
27 import org.apache.commons.lang.LocaleUtils;
28 import org.apache.maven.artifact.factory.ArtifactFactory;
29 import org.apache.maven.artifact.repository.ArtifactRepository;
30 import org.apache.maven.artifact.resolver.ArtifactResolver;
31 import org.apache.maven.doxia.module.xhtml.decoration.render.RenderingContext;
32 import org.apache.maven.doxia.site.decoration.Body;
33 import org.apache.maven.doxia.site.decoration.DecorationModel;
34 import org.apache.maven.doxia.siterenderer.Renderer;
35 import org.apache.maven.doxia.siterenderer.RendererException;
36 import org.apache.maven.doxia.siterenderer.SiteRenderingContext;
37 import org.apache.maven.doxia.siterenderer.sink.SiteRendererSink;
38 import org.apache.maven.plugin.MojoExecutionException;
39 import org.apache.maven.plugin.logging.Log;
40 import org.apache.maven.project.MavenProject;
41 import org.apache.maven.reporting.AbstractMavenReport;
42 import org.apache.maven.reporting.MavenReportException;
43 import org.codehaus.plexus.util.StringUtils;
44
45 import de.smartics.maven.util.LoggingUtils;
46 import de.smartics.maven.util.report.ReportUtils;
47
48 /**
49 * The Mojo reports on issues reported by the Javadoc tool.
50 *
51 * @author <a href="mailto:robert.reiner@smartics.de">Robert Reiner</a>
52 * @version $Revision:591 $
53 */
54 public abstract class AbstractReportMojo extends AbstractMavenReport
55 {
56 // ********************************* Fields *********************************
57
58 // --- constants ------------------------------------------------------------
59
60 // --- members --------------------------------------------------------------
61
62 // ... plugin infrastructure ................................................
63
64 /**
65 * The Maven project.
66 *
67 * @parameter expression="${project}"
68 * @required
69 * @readonly
70 */
71 protected MavenProject project;
72
73 /**
74 * The Doxia site renderer.
75 *
76 * @component
77 * @required
78 * @readonly
79 */
80 protected Renderer siteRenderer;
81
82 /**
83 * Local Repository.
84 *
85 * @parameter expression="${localRepository}"
86 * @required
87 * @readonly
88 */
89 protected ArtifactRepository localRepository;
90
91 /**
92 * The resolver for resolving artifacts.
93 *
94 * @component
95 * @required
96 * @readonly
97 */
98 protected ArtifactResolver resolver;
99
100 /**
101 * The factory to create dependent artifacts.
102 *
103 * @component
104 * @required
105 * @readonly
106 */
107 protected ArtifactFactory factory;
108
109 // ... report configuration parameters ......................................
110
111 /**
112 * Specifies the directory where the report will written to. This information
113 * is only used if the report is not part of the site generation process.
114 *
115 * @parameter expression="${project.reporting.outputDirectory}"
116 * @readonly
117 */
118 protected File outputDirectory;
119
120 /**
121 * Specifies the log level used for this plugin.
122 * <p>
123 * Allowed values are <code>SEVERE</code>, <code>WARNING</code>,
124 * <code>INFO</code> and <code>FINEST</code>.
125 * </p>
126 *
127 * @parameter expression="${apidoc.logLevel}"
128 * @since 1.0
129 */
130 protected String logLevel;
131
132 /**
133 * The locale to use regardless of the report. This should be set to the
134 * locale the Javadoc comment is written in. If not set, the Maven provided
135 * locale is used.
136 *
137 * @parameter expression="${apidoc.locale}"
138 * @since 1.0
139 */
140 protected String locale;
141
142 /**
143 * A simple flag to skip the generation of the reports. If set on the command
144 * line use <code>-Dapidoc.skip</code>.
145 *
146 * @parameter expression="${apidoc.skip}" default-value="false"
147 * @since 1.0
148 */
149 protected boolean skip;
150
151 // ****************************** Initializer *******************************
152
153 // ****************************** Constructors ******************************
154
155 // ****************************** Inner Classes *****************************
156
157 // ********************************* Methods ********************************
158
159 // --- init -----------------------------------------------------------------
160
161 // --- get&set --------------------------------------------------------------
162
163 // ... plugin infrastructure ................................................
164
165 /**
166 * {@inheritDoc}
167 *
168 * @see org.apache.maven.reporting.AbstractMavenReport#getProject()
169 */
170 @Override
171 protected MavenProject getProject()
172 {
173 return project;
174 }
175
176 /**
177 * {@inheritDoc}
178 *
179 * @see org.apache.maven.reporting.AbstractMavenReport#getSiteRenderer()
180 */
181 @Override
182 protected Renderer getSiteRenderer()
183 {
184 return siteRenderer;
185 }
186
187 // ... report configuration parameters ......................................
188
189 // ... basics
190
191 /**
192 * {@inheritDoc}
193 *
194 * @see org.apache.maven.reporting.AbstractMavenReport#getOutputDirectory()
195 */
196 @Override
197 protected String getOutputDirectory()
198 {
199 return outputDirectory.getAbsolutePath();
200 }
201
202 // --- business -------------------------------------------------------------
203
204 /**
205 * Runs the report generation.
206 *
207 * @throws MojoExecutionException on any problem encountered.
208 */
209 public void execute() throws MojoExecutionException
210 {
211 final Log log = getLog();
212 if (!canGenerateReport())
213 {
214 if (log.isInfoEnabled())
215 {
216 log.info("Report '" + getName(Locale.getDefault())
217 + "' skipped due to offline mode.");
218 }
219 return;
220 }
221
222 LoggingUtils.configureLogger(log, logLevel);
223
224 provideSink();
225 }
226
227 /**
228 * {@inheritDoc}
229 * <p>
230 * Configures the plugin logger.
231 * </p>
232 *
233 * @see org.apache.maven.reporting.AbstractMavenReport#executeReport(java.util.Locale)
234 */
235 @Override
236 protected void executeReport(final Locale locale) throws MavenReportException
237 {
238 final Log log = getLog();
239 LoggingUtils.configureLogger(log, logLevel);
240 }
241
242 /**
243 * Checks if all required information is provided to run the report
244 * successfully. If the plugin is running in offline mode, this method returns
245 * <code>false</code>.
246 *
247 * @return <code>true</code> if a report can be rendered, <code>false</code>
248 * otherwise.
249 * @see org.apache.maven.reporting.AbstractMavenReport#canGenerateReport()
250 */
251 @Override
252 public boolean canGenerateReport()
253 {
254 return !skip;
255 }
256
257 /**
258 * Ensures that a writeable sink is provided.
259 * <p>
260 * Stolen from the changes plugin.
261 * </p>
262 *
263 * @throws MojoExecutionException if the sink cannot be created.
264 */
265 protected void provideSink() throws MojoExecutionException
266 {
267 final Locale reportLocale = determineLocale();
268
269 try
270 {
271 final DecorationModel model = new DecorationModel();
272 model.setBody(new Body());
273 final Map<String, String> attributes = new HashMap<String, String>();
274 attributes.put("outputEncoding", "UTF-8"); // TODO correct???
275 final SiteRenderingContext siteContext =
276 siteRenderer.createContextForSkin(ReportUtils.getSkinArtifactFile(
277 project, localRepository, resolver, factory), attributes, model,
278 getName(reportLocale), reportLocale);
279
280 final RenderingContext context =
281 new RenderingContext(outputDirectory, getOutputName() + ".html");
282
283 final SiteRendererSink sink = new SiteRendererSink(context);
284 generate(sink, reportLocale);
285
286 if (!outputDirectory.exists() && !outputDirectory.mkdirs())
287 {
288 throw new IOException("Cannot generate directories '"
289 + outputDirectory.getPath() + "'");
290 }
291
292 // The writer will be closed by the renderer
293 // http://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/xref/index.html
294 final Writer writer =
295 new FileWriter(new File(outputDirectory, getOutputName() + ".html"));
296 siteRenderer.generateDocument(writer, sink, siteContext);
297
298 siteRenderer.copyResources(siteContext, new File(project.getBasedir(),
299 "src/site/resources"), outputDirectory);
300 }
301 catch (final RendererException e)
302 {
303 throw new MojoExecutionException(createErrorMessage(reportLocale), e);
304 }
305 catch (final IOException e)
306 {
307 throw new MojoExecutionException(createErrorMessage(reportLocale), e);
308 }
309 catch (final MavenReportException e)
310 {
311 throw new MojoExecutionException(createErrorMessage(reportLocale), e);
312 }
313 }
314
315 /**
316 * Creates an error message signaling a problem with the report generation.
317 *
318 * @param reportLocale the locale to select the report name.
319 * @return the error message for failed report generation.
320 */
321 private String createErrorMessage(final Locale reportLocale)
322 {
323 return "An error has occurred in " + getName(reportLocale)
324 + " report generation.";
325 }
326
327 /**
328 * Determines the locale to use. The plugin allows the user to override the
329 * locale provided by Maven.
330 *
331 * @return the locale to use for this report.
332 */
333 private Locale determineLocale()
334 {
335 return StringUtils.isNotBlank(this.locale) ? LocaleUtils
336 .toLocale(this.locale) : Locale.getDefault();
337 }
338
339 /**
340 * Returns the resource bundle for the given locale.
341 *
342 * @param locale the locale for which the resource bundle is requested.
343 * @return the bundle for the given locale.
344 */
345 protected ResourceBundle getBundle(final Locale locale)
346 {
347 return ResourceBundle.getBundle("de.smartics.maven.apidoc.ApidocReport",
348 locale);
349 }
350
351 // --- object basics --------------------------------------------------------
352
353 }