View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.maven.plugins.site.render;
20  
21  import java.io.File;
22  import java.io.IOException;
23  import java.util.ArrayList;
24  import java.util.Collection;
25  import java.util.Date;
26  import java.util.HashMap;
27  import java.util.Iterator;
28  import java.util.LinkedHashMap;
29  import java.util.List;
30  import java.util.Locale;
31  import java.util.Map;
32  
33  import org.apache.maven.archiver.MavenArchiver;
34  import org.apache.maven.artifact.Artifact;
35  import org.apache.maven.doxia.site.Menu;
36  import org.apache.maven.doxia.site.MenuItem;
37  import org.apache.maven.doxia.site.SiteModel;
38  import org.apache.maven.doxia.siterenderer.DocumentRenderer;
39  import org.apache.maven.doxia.siterenderer.DocumentRenderingContext;
40  import org.apache.maven.doxia.siterenderer.RendererException;
41  import org.apache.maven.doxia.siterenderer.SiteRenderer;
42  import org.apache.maven.doxia.siterenderer.SiteRenderingContext;
43  import org.apache.maven.doxia.tools.SiteTool;
44  import org.apache.maven.doxia.tools.SiteToolException;
45  import org.apache.maven.execution.MavenSession;
46  import org.apache.maven.model.ReportPlugin;
47  import org.apache.maven.model.Reporting;
48  import org.apache.maven.plugin.MojoExecution;
49  import org.apache.maven.plugin.MojoExecutionException;
50  import org.apache.maven.plugin.MojoFailureException;
51  import org.apache.maven.plugins.annotations.Component;
52  import org.apache.maven.plugins.annotations.Parameter;
53  import org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo;
54  import org.apache.maven.reporting.MavenReport;
55  import org.apache.maven.reporting.MavenReportException;
56  import org.apache.maven.reporting.exec.MavenReportExecution;
57  import org.apache.maven.reporting.exec.MavenReportExecutor;
58  import org.apache.maven.reporting.exec.MavenReportExecutorRequest;
59  import org.apache.maven.shared.utils.WriterFactory;
60  import org.codehaus.plexus.util.ReaderFactory;
61  
62  import static org.apache.maven.shared.utils.logging.MessageUtils.buffer;
63  
64  /**
65   * Base class for site rendering mojos.
66   *
67   * @author <a href="mailto:brett@apache.org">Brett Porter</a>
68   *
69   */
70  public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMojo {
71      /**
72       * Module type exclusion mappings
73       * ex: <code>fml  -> **&#47;*-m1.fml</code>  (excludes fml files ending in '-m1.fml' recursively)
74       * <p/>
75       * The configuration looks like this:
76       * <pre>
77       *   &lt;moduleExcludes&gt;
78       *     &lt;moduleType&gt;filename1.ext,**&#47;*sample.ext&lt;/moduleType&gt;
79       *     &lt;!-- moduleType can be one of 'apt', 'fml' or 'xdoc'. --&gt;
80       *     &lt;!-- The value is a comma separated list of           --&gt;
81       *     &lt;!-- filenames or fileset patterns.                   --&gt;
82       *     &lt;!-- Here's an example:                               --&gt;
83       *     &lt;xdoc&gt;changes.xml,navigation.xml&lt;/xdoc&gt;
84       *   &lt;/moduleExcludes&gt;
85       * </pre>
86       */
87      @Parameter
88      private Map<String, String> moduleExcludes;
89  
90      /**
91       * Additional template properties for rendering the site. See
92       * <a href="/doxia/doxia-sitetools/doxia-site-renderer/">Doxia Site Renderer</a>.
93       */
94      @Parameter
95      private Map<String, Object> attributes;
96  
97      /**
98       * Site renderer.
99       */
100     @Component
101     protected SiteRenderer siteRenderer;
102 
103     /**
104      * Directory containing generated documentation in source format (Doxia supported markup).
105      * This is used to pick up other source docs that might have been generated at build time (by reports or any other
106      * build time mean).
107      * This directory is expected to have the same structure as <code>siteDirectory</code>
108      * (ie. one directory per Doxia-source-supported markup types).
109      *
110      * todo should we deprecate in favour of reports directly using Doxia Sink API, without this Doxia source
111      * intermediate step?
112      */
113     @Parameter(alias = "workingDirectory", defaultValue = "${project.build.directory}/generated-site")
114     protected File generatedSiteDirectory;
115 
116     /**
117      * The current Maven session.
118      */
119     @Parameter(defaultValue = "${session}", readonly = true, required = true)
120     protected MavenSession mavenSession;
121 
122     /**
123      * The mojo execution
124      */
125     @Parameter(defaultValue = "${mojoExecution}", readonly = true, required = true)
126     protected MojoExecution mojoExecution;
127 
128     /**
129      * replaces previous reportPlugins parameter, that was injected by Maven core from
130      * reporting section: but this new configuration format has been abandoned.
131      *
132      * @since 3.7.1
133      */
134     @Parameter(defaultValue = "${project.reporting}", readonly = true)
135     private Reporting reporting;
136 
137     /**
138      * Whether to generate the summary page for project reports: project-info.html.
139      *
140      * @since 2.3
141      */
142     @Parameter(property = "generateProjectInfo", defaultValue = "true")
143     private boolean generateProjectInfo;
144 
145     /**
146      * Generate a sitemap. The result will be a "sitemap.html" file at the site root.
147      *
148      * @since 2.1
149      */
150     @Parameter(property = "generateSitemap", defaultValue = "false")
151     private boolean generateSitemap;
152 
153     /**
154      * Specifies the input encoding.
155      *
156      * @since 2.3
157      */
158     @Parameter(property = "encoding", defaultValue = "${project.build.sourceEncoding}")
159     private String inputEncoding;
160 
161     /**
162      * Specifies the output encoding.
163      *
164      * @since 2.3
165      */
166     @Parameter(property = "outputEncoding", defaultValue = "${project.reporting.outputEncoding}")
167     private String outputEncoding;
168 
169     /**
170      * Timestamp for reproducible output archive entries, either formatted as ISO 8601
171      * <code>yyyy-MM-dd'T'HH:mm:ssXXX</code> or as an int representing seconds since the epoch (like
172      * <a href="https://reproducible-builds.org/docs/source-date-epoch/">SOURCE_DATE_EPOCH</a>).
173      *
174      * @since 3.9.0
175      */
176     @Parameter(defaultValue = "${project.build.outputTimestamp}")
177     protected String outputTimestamp;
178 
179     @Component
180     protected MavenReportExecutor mavenReportExecutor;
181 
182     /**
183      * Gets the input files encoding.
184      *
185      * @return The input files encoding, never <code>null</code>.
186      */
187     protected String getInputEncoding() {
188         return (inputEncoding == null || inputEncoding.isEmpty()) ? ReaderFactory.FILE_ENCODING : inputEncoding;
189     }
190 
191     /**
192      * Gets the effective reporting output files encoding.
193      *
194      * @return The effective reporting output file encoding, never <code>null</code>.
195      */
196     protected String getOutputEncoding() {
197         return (outputEncoding == null) ? WriterFactory.UTF_8 : outputEncoding;
198     }
199 
200     /**
201      * Whether to save Velocity processed Doxia content (<code>*.&lt;ext&gt;.vm</code>)
202      * to <code>${generatedSiteDirectory}/processed</code>.
203      *
204      * @since 3.5
205      */
206     @Parameter
207     private boolean saveProcessedContent;
208 
209     protected void checkInputEncoding() {
210         if (inputEncoding == null || inputEncoding.isEmpty()) {
211             getLog().warn("Input file encoding has not been set, using platform encoding " + ReaderFactory.FILE_ENCODING
212                     + ", i.e. build is platform dependent!");
213         }
214     }
215 
216     protected List<MavenReportExecution> getReports(File outputDirectory) throws MojoExecutionException {
217         MavenReportExecutorRequest mavenReportExecutorRequest = new MavenReportExecutorRequest();
218         mavenReportExecutorRequest.setMavenSession(mavenSession);
219         mavenReportExecutorRequest.setExecutionId(mojoExecution.getExecutionId());
220         mavenReportExecutorRequest.setProject(project);
221         mavenReportExecutorRequest.setReportPlugins(getReportingPlugins());
222 
223         List<MavenReportExecution> allReports = mavenReportExecutor.buildMavenReports(mavenReportExecutorRequest);
224 
225         // filter out reports that can't be generated
226         List<MavenReportExecution> reportExecutions = new ArrayList<>(allReports.size());
227         for (MavenReportExecution exec : allReports) {
228             String reportMojoInfo = exec.getPlugin().getId() + ":" + exec.getGoal();
229             exec.getMavenReport().setReportOutputDirectory(outputDirectory);
230             try {
231                 if (exec.canGenerateReport()) {
232                     reportExecutions.add(exec);
233                 } else if (exec.isUserDefined()) {
234                     getLog().info("Skipping " + reportMojoInfo + " report");
235                 }
236             } catch (MavenReportException e) {
237                 throw new MojoExecutionException(
238                         "Failed to determine whether report '" + reportMojoInfo + "' can be generated", e);
239             }
240         }
241         return reportExecutions;
242     }
243 
244     /**
245      * Get the report plugins from reporting section, adding if necessary (i.e. not excluded)
246      * default reports (i.e. maven-project-info-reports)
247      *
248      * @return the effective list of reports
249      * @since 3.7.1
250      */
251     private ReportPlugin[] getReportingPlugins() {
252         List<ReportPlugin> reportingPlugins = reporting.getPlugins();
253 
254         // MSITE-806: add default report plugin like done in maven-model-builder DefaultReportingConverter
255         boolean hasMavenProjectInfoReportsPlugin = false;
256         for (ReportPlugin plugin : reportingPlugins) {
257             if ("org.apache.maven.plugins".equals(plugin.getGroupId())
258                     && "maven-project-info-reports-plugin".equals(plugin.getArtifactId())) {
259                 hasMavenProjectInfoReportsPlugin = true;
260                 break;
261             }
262         }
263 
264         if (!reporting.isExcludeDefaults() && !hasMavenProjectInfoReportsPlugin) {
265             ReportPlugin mpir = new ReportPlugin();
266             mpir.setArtifactId("maven-project-info-reports-plugin");
267             reportingPlugins.add(mpir);
268         }
269         return reportingPlugins.toArray(new ReportPlugin[0]);
270     }
271 
272     protected SiteRenderingContext createSiteRenderingContext(Locale locale)
273             throws MojoExecutionException, IOException, MojoFailureException {
274         SiteModel siteModel = prepareSiteModel(locale);
275         Map<String, Object> templateProperties = new HashMap<>();
276         templateProperties.put("project", project);
277         templateProperties.put("inputEncoding", getInputEncoding());
278         templateProperties.put("outputEncoding", getOutputEncoding());
279 
280         // Put any of the properties in directly into the Velocity context
281         for (Map.Entry<Object, Object> entry : project.getProperties().entrySet()) {
282             templateProperties.put((String) entry.getKey(), entry.getValue());
283         }
284 
285         // Comes last if someone wants to deliberately override any default or model properties
286         if (attributes != null) {
287             templateProperties.putAll(attributes);
288         }
289 
290         SiteRenderingContext context;
291         try {
292             Artifact skinArtifact =
293                     siteTool.getSkinArtifactFromRepository(repoSession, remoteProjectRepositories, siteModel.getSkin());
294 
295             getLog().info(buffer().a("Rendering content with ")
296                     .strong(skinArtifact.getId() + " skin")
297                     .toString());
298 
299             context = siteRenderer.createContextForSkin(
300                     skinArtifact, templateProperties, siteModel, project.getName(), locale);
301         } catch (SiteToolException e) {
302             throw new MojoExecutionException("Failed to retrieve skin artifact from repository", e);
303         } catch (RendererException e) {
304             throw new MojoExecutionException("Failed to create context for skin", e);
305         }
306 
307         // Add publish date
308         MavenArchiver.parseBuildOutputTimestamp(outputTimestamp).ifPresent(v -> {
309             context.setPublishDate(Date.from(v));
310         });
311 
312         // Generate static site
313         context.setRootDirectory(project.getBasedir());
314         if (!locale.equals(SiteTool.DEFAULT_LOCALE)) {
315             context.addSiteDirectory(new File(siteDirectory, locale.toString()));
316         } else {
317             context.addSiteDirectory(siteDirectory);
318         }
319 
320         if (moduleExcludes != null) {
321             context.setModuleExcludes(moduleExcludes);
322         }
323 
324         if (saveProcessedContent) {
325             File processedDir = new File(generatedSiteDirectory, "processed");
326             if (!locale.equals(SiteTool.DEFAULT_LOCALE)) {
327                 context.setProcessedContentOutput(new File(processedDir, locale.toString()));
328             } else {
329                 context.setProcessedContentOutput(processedDir);
330             }
331         }
332 
333         return context;
334     }
335 
336     /**
337      * Go through the list of reports and process each one like this:
338      * <ul>
339      * <li>Add the report to a map of reports keyed by filename having the report itself as value
340      * <li>If the report is not yet in the map of documents, add it together with a suitable renderer
341      * </ul>
342      *
343      * @param reports A List of MavenReports
344      * @param documents A Map of documents, keyed by filename
345      * @param locale the Locale the reports are processed for.
346      * @return A map with all reports keyed by filename having the report itself as value.
347      * The map will be used to populate a menu.
348      */
349     protected Map<String, MavenReport> locateReports(
350             List<MavenReportExecution> reports, Map<String, DocumentRenderer> documents, Locale locale) {
351         Map<String, MavenReport> reportsByOutputName = new LinkedHashMap<>();
352         for (MavenReportExecution mavenReportExecution : reports) {
353             MavenReport report = mavenReportExecution.getMavenReport();
354 
355             String outputName = report.getOutputName();
356             String filename = outputName + ".html";
357 
358             // Always add the report to the menu, see MSITE-150
359             reportsByOutputName.put(outputName, report);
360 
361             if (documents.containsKey(filename)) {
362                 String reportMojoInfo = mavenReportExecution.getGoal() == null
363                         ? ""
364                         : (" (" + mavenReportExecution.getPlugin().getArtifactId() + ':'
365                                 + mavenReportExecution.getPlugin().getVersion() + ':' + mavenReportExecution.getGoal()
366                                 + ')');
367 
368                 getLog().info("Skipped \"" + report.getName(locale) + "\" report" + reportMojoInfo + ", file \""
369                         + filename + "\" already exists.");
370             } else {
371                 File localizedSiteDirectory;
372                 if (!locale.equals(SiteTool.DEFAULT_LOCALE)) {
373                     localizedSiteDirectory = new File(siteDirectory, locale.toString());
374                 } else {
375                     localizedSiteDirectory = siteDirectory;
376                 }
377                 String generator = mavenReportExecution.getGoal() == null
378                         ? null
379                         : mavenReportExecution.getPlugin().getId() + ':' + mavenReportExecution.getGoal();
380                 DocumentRenderingContext docRenderingContext =
381                         new DocumentRenderingContext(localizedSiteDirectory, outputName, generator);
382                 DocumentRenderer docRenderer =
383                         new ReportDocumentRenderer(mavenReportExecution, docRenderingContext, getLog());
384                 documents.put(filename, docRenderer);
385             }
386         }
387         return reportsByOutputName;
388     }
389 
390     /**
391      * Go through the collection of reports and put each report into a list for the appropriate category. The list is
392      * put into a map keyed by the name of the category.
393      *
394      * @param reports A Collection of MavenReports
395      * @return A map keyed category having the report itself as value
396      */
397     protected Map<String, List<MavenReport>> categoriseReports(Collection<MavenReport> reports) {
398         Map<String, List<MavenReport>> categories = new LinkedHashMap<>();
399         for (MavenReport report : reports) {
400             List<MavenReport> categoryReports = categories.get(report.getCategoryName());
401             if (categoryReports == null) {
402                 categoryReports = new ArrayList<>();
403                 categories.put(report.getCategoryName(), categoryReports);
404             }
405             categoryReports.add(report);
406         }
407         return categories;
408     }
409 
410     /**
411      * Locate every document to be rendered for given locale:<ul>
412      * <li>handwritten content, ie Doxia files,</li>
413      * <li>reports,</li>
414      * <li>"Project Information" and "Project Reports" category summaries.</li>
415      * </ul>
416      *
417      * @param context the site context
418      * @param reports the documents
419      * @param locale the locale
420      * @return the documents and their renderers
421      * @throws IOException in case of file reading issue
422      * @throws RendererException in case of Doxia rendering issue
423      * @see CategorySummaryDocumentRenderer
424      */
425     protected Map<String, DocumentRenderer> locateDocuments(
426             SiteRenderingContext context, List<MavenReportExecution> reports, Locale locale)
427             throws IOException, RendererException {
428         Map<String, DocumentRenderer> documents = siteRenderer.locateDocumentFiles(context, true);
429 
430         Map<String, MavenReport> reportsByOutputName = locateReports(reports, documents, locale);
431 
432         // TODO: I want to get rid of categories eventually. There's no way to add your own in a fully i18n manner
433         Map<String, List<MavenReport>> categories = categoriseReports(reportsByOutputName.values());
434 
435         siteTool.populateReportsMenu(context.getSiteModel(), locale, categories);
436         populateReportItems(context.getSiteModel(), locale, reportsByOutputName);
437 
438         File localizedSiteDirectory;
439         if (!locale.equals(SiteTool.DEFAULT_LOCALE)) {
440             localizedSiteDirectory = new File(siteDirectory, locale.toString());
441         } else {
442             localizedSiteDirectory = siteDirectory;
443         }
444 
445         if (categories.containsKey(MavenReport.CATEGORY_PROJECT_INFORMATION) && generateProjectInfo) {
446             // add "Project Information" category summary document
447             List<MavenReport> categoryReports = categories.get(MavenReport.CATEGORY_PROJECT_INFORMATION);
448             MojoExecution subMojoExecution =
449                     new MojoExecution(mojoExecution.getPlugin(), "project-info", mojoExecution.getExecutionId());
450             DocumentRenderingContext docRenderingContext = new DocumentRenderingContext(
451                     localizedSiteDirectory,
452                     subMojoExecution.getGoal(),
453                     subMojoExecution.getPlugin().getId() + ':' + subMojoExecution.getGoal());
454             String title = i18n.getString("site-plugin", locale, "report.information.title");
455             String desc1 = i18n.getString("site-plugin", locale, "report.information.description1");
456             String desc2 = i18n.getString("site-plugin", locale, "report.information.description2");
457             DocumentRenderer docRenderer = new CategorySummaryDocumentRenderer(
458                     subMojoExecution, docRenderingContext, title, desc1, desc2, i18n, categoryReports, getLog());
459 
460             String filename = docRenderer.getOutputName();
461             if (!documents.containsKey(filename)) {
462                 documents.put(filename, docRenderer);
463             } else {
464                 getLog().info("Skipped \"" + title + "\" report; file \"" + filename + "\" already exists.");
465             }
466         }
467 
468         if (categories.containsKey(MavenReport.CATEGORY_PROJECT_REPORTS)) {
469             // add "Project Reports" category summary document
470             List<MavenReport> categoryReports = categories.get(MavenReport.CATEGORY_PROJECT_REPORTS);
471             MojoExecution subMojoExecution =
472                     new MojoExecution(mojoExecution.getPlugin(), "project-reports", mojoExecution.getExecutionId());
473             DocumentRenderingContext docRenderingContext = new DocumentRenderingContext(
474                     localizedSiteDirectory,
475                     subMojoExecution.getGoal(),
476                     subMojoExecution.getPlugin().getId() + ':' + subMojoExecution.getGoal());
477             String title = i18n.getString("site-plugin", locale, "report.project.title");
478             String desc1 = i18n.getString("site-plugin", locale, "report.project.description1");
479             String desc2 = i18n.getString("site-plugin", locale, "report.project.description2");
480             DocumentRenderer docRenderer = new CategorySummaryDocumentRenderer(
481                     subMojoExecution, docRenderingContext, title, desc1, desc2, i18n, categoryReports, getLog());
482 
483             String filename = docRenderer.getOutputName();
484             if (!documents.containsKey(filename)) {
485                 documents.put(filename, docRenderer);
486             } else {
487                 getLog().info("Skipped \"" + title + "\" report; file \"" + filename + "\" already exists.");
488             }
489         }
490 
491         if (generateSitemap) {
492             MojoExecution subMojoExecution =
493                     new MojoExecution(mojoExecution.getPlugin(), "sitemap", mojoExecution.getExecutionId());
494             DocumentRenderingContext docRenderingContext = new DocumentRenderingContext(
495                     localizedSiteDirectory,
496                     subMojoExecution.getGoal(),
497                     subMojoExecution.getPlugin().getId() + ':' + subMojoExecution.getGoal());
498             String title = i18n.getString("site-plugin", locale, "site.sitemap.title");
499             DocumentRenderer docRenderer = new SitemapDocumentRenderer(
500                     subMojoExecution, docRenderingContext, title, context.getSiteModel(), i18n, getLog());
501 
502             String filename = docRenderer.getOutputName();
503             if (!documents.containsKey(filename)) {
504                 documents.put(filename, docRenderer);
505             } else {
506                 getLog().info("Skipped \"" + title + "\" report; file \"" + filename + "\" already exists.");
507             }
508         }
509 
510         return documents;
511     }
512 
513     protected void populateReportItems(
514             SiteModel siteModel, Locale locale, Map<String, MavenReport> reportsByOutputName) {
515         for (Menu menu : siteModel.getMenus()) {
516             populateItemRefs(menu.getItems(), locale, reportsByOutputName);
517         }
518     }
519 
520     private void populateItemRefs(List<MenuItem> items, Locale locale, Map<String, MavenReport> reportsByOutputName) {
521         for (Iterator<MenuItem> i = items.iterator(); i.hasNext(); ) {
522             MenuItem item = i.next();
523 
524             if (item.getRef() != null) {
525                 MavenReport report = reportsByOutputName.get(item.getRef());
526 
527                 if (report != null) {
528                     if (item.getName() == null) {
529                         item.setName(report.getName(locale));
530                     }
531 
532                     if (item.getHref() == null || item.getHref().length() == 0) {
533                         item.setHref(report.getOutputName() + ".html");
534                     }
535                 } else {
536                     getLog().warn("Unrecognised reference: '" + item.getRef() + "'");
537                     i.remove();
538                 }
539             }
540 
541             populateItemRefs(item.getItems(), locale, reportsByOutputName);
542         }
543     }
544 }