View Javadoc
1   package org.apache.maven.plugins.site.render;
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.io.IOException;
24  import java.util.ArrayList;
25  import java.util.Collection;
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.artifact.Artifact;
34  import org.apache.maven.doxia.site.decoration.DecorationModel;
35  import org.apache.maven.doxia.site.decoration.Menu;
36  import org.apache.maven.doxia.site.decoration.MenuItem;
37  import org.apache.maven.doxia.siterenderer.DocumentRenderer;
38  import org.apache.maven.doxia.siterenderer.Renderer;
39  import org.apache.maven.doxia.siterenderer.RendererException;
40  import org.apache.maven.doxia.siterenderer.RenderingContext;
41  import org.apache.maven.doxia.siterenderer.SiteRenderingContext;
42  import org.apache.maven.doxia.tools.SiteToolException;
43  import org.apache.maven.execution.MavenSession;
44  import org.apache.maven.model.ReportPlugin;
45  import org.apache.maven.plugin.MojoExecutionException;
46  import org.apache.maven.plugin.MojoFailureException;
47  import org.apache.maven.plugin.descriptor.PluginDescriptor;
48  import org.apache.maven.plugins.annotations.Component;
49  import org.apache.maven.plugins.annotations.Parameter;
50  import org.apache.maven.plugins.site.descriptor.AbstractSiteDescriptorMojo;
51  import org.apache.maven.reporting.MavenReport;
52  import org.apache.maven.reporting.exec.MavenReportExecution;
53  import org.apache.maven.reporting.exec.MavenReportExecutor;
54  import org.apache.maven.reporting.exec.MavenReportExecutorRequest;
55  import org.codehaus.plexus.PlexusConstants;
56  import org.codehaus.plexus.PlexusContainer;
57  import org.codehaus.plexus.component.repository.exception.ComponentLookupException;
58  import org.codehaus.plexus.context.Context;
59  import org.codehaus.plexus.context.ContextException;
60  import org.codehaus.plexus.personality.plexus.lifecycle.phase.Contextualizable;
61  import org.codehaus.plexus.util.ReaderFactory;
62  import org.codehaus.plexus.util.StringUtils;
63  
64  /**
65   * Base class for site rendering mojos.
66   *
67   * @author <a href="mailto:brett@apache.org">Brett Porter</a>
68   * @version $Id$
69   */
70  public abstract class AbstractSiteRenderingMojo
71      extends AbstractSiteDescriptorMojo implements Contextualizable
72  {
73      /**
74       * Module type exclusion mappings
75       * ex: <code>fml  -> **&#47;*-m1.fml</code>  (excludes fml files ending in '-m1.fml' recursively)
76       * <p/>
77       * The configuration looks like this:
78       * <pre>
79       *   &lt;moduleExcludes&gt;
80       *     &lt;moduleType&gt;filename1.ext,**&#47;*sample.ext&lt;/moduleType&gt;
81       *     &lt;!-- moduleType can be one of 'apt', 'fml' or 'xdoc'. --&gt;
82       *     &lt;!-- The value is a comma separated list of           --&gt;
83       *     &lt;!-- filenames or fileset patterns.                   --&gt;
84       *     &lt;!-- Here's an example:                               --&gt;
85       *     &lt;xdoc&gt;changes.xml,navigation.xml&lt;/xdoc&gt;
86       *   &lt;/moduleExcludes&gt;
87       * </pre>
88       */
89      @Parameter
90      private Map<String, String> moduleExcludes;
91  
92      /**
93       * The location of a Velocity template file to use. When used, skins and the default templates, CSS and images
94       * are disabled. It is highly recommended that you package this as a skin instead.
95       *
96       * @since 2.0-beta-5
97       */
98      @Parameter( property = "templateFile" )
99      private File templateFile;
100 
101     /**
102      * Additional template properties for rendering the site. See
103      * <a href="/doxia/doxia-sitetools/doxia-site-renderer/">Doxia Site Renderer</a>.
104      */
105     @Parameter
106     private Map<String, Object> attributes;
107 
108     /**
109      * Site renderer.
110      */
111     @Component
112     protected Renderer siteRenderer;
113 
114     /**
115      * Reports (Maven 2).
116      */
117     @Parameter( defaultValue = "${reports}", required = true, readonly = true )
118     protected List<MavenReport> reports;
119 
120     /**
121      * Alternative directory for xdoc source, useful for m1 to m2 migration
122      *
123      * @deprecated use the standard m2 directory layout
124      */
125     @Parameter( defaultValue = "${basedir}/xdocs" )
126     private File xdocDirectory;
127 
128     /**
129      * Directory containing generated documentation in source format (Doxia supported markup).
130      * This is used to pick up other source docs that might have been generated at build time (by reports or any other
131      * build time mean).
132      * This directory is expected to have the same structure as <code>siteDirectory</code>
133      * (ie. one directory per Doxia-source-supported markup types).
134      *
135      * @todo should we deprecate in favour of reports directly using Doxia Sink API, without this Doxia source
136      * intermediate step?
137      */
138     @Parameter( alias = "workingDirectory", defaultValue = "${project.build.directory}/generated-site" )
139     protected File generatedSiteDirectory;
140 
141     /**
142      * The current Maven session.
143      */
144     @Parameter( defaultValue = "${session}", readonly = true, required = true )
145     protected MavenSession mavenSession;
146 
147     /**
148      * replaces previous reportPlugins parameter, that was injected by Maven core from
149      * reporting section: but this new configuration format has been abandoned.
150      * @since 3.7
151      */
152     @Parameter( defaultValue = "${project.reporting.plugins}", readonly = true )
153     private ReportPlugin[] reportingPlugins;
154 
155     private PlexusContainer container;
156 
157     /**
158      * Whether to generate the summary page for project reports: project-info.html.
159      *
160      * @since 2.3
161      */
162     @Parameter( property = "generateProjectInfo", defaultValue = "true" )
163     private boolean generateProjectInfo;
164 
165     /**
166      * Specifies the input encoding.
167      *
168      * @since 2.3
169      */
170     @Parameter( property = "encoding", defaultValue = "${project.build.sourceEncoding}" )
171     private String inputEncoding;
172 
173     /**
174      * Specifies the output encoding.
175      *
176      * @since 2.3
177      */
178     @Parameter( property = "outputEncoding", defaultValue = "${project.reporting.outputEncoding}" )
179     private String outputEncoding;
180 
181     /**
182      * Gets the input files encoding.
183      *
184      * @return The input files encoding, never <code>null</code>.
185      */
186     protected String getInputEncoding()
187     {
188         return ( StringUtils.isEmpty( inputEncoding ) ) ? 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     {
198         return ( outputEncoding == null ) ? ReaderFactory.UTF_8 : outputEncoding;
199     }
200 
201     /**
202      * Whether to save Velocity processed Doxia content (<code>*.&lt;ext&gt;.vm</code>)
203      * to <code>${generatedSiteDirectory}/processed</code>.
204      *
205      * @since 3.5
206      */
207     @Parameter
208     private boolean saveProcessedContent;
209 
210     /** {@inheritDoc} */
211     public void contextualize( Context context )
212         throws ContextException
213     {
214         container = (PlexusContainer) context.get( PlexusConstants.PLEXUS_KEY );
215     }
216 
217     protected void checkInputEncoding()
218     {
219         if ( StringUtils.isEmpty( inputEncoding ) )
220         {
221             getLog().warn( "Input file encoding has not been set, using platform encoding "
222                 + ReaderFactory.FILE_ENCODING + ", i.e. build is platform dependent!" );
223         }
224     }
225 
226     protected List<MavenReportExecution> getReports()
227         throws MojoExecutionException
228     {
229         List<MavenReportExecution> allReports;
230 
231         if ( isMaven3OrMore() )
232         {
233             // Maven 3
234             MavenReportExecutorRequest mavenReportExecutorRequest = new MavenReportExecutorRequest();
235             mavenReportExecutorRequest.setLocalRepository( localRepository );
236             mavenReportExecutorRequest.setMavenSession( mavenSession );
237             mavenReportExecutorRequest.setProject( project );
238             mavenReportExecutorRequest.setReportPlugins( reportingPlugins );
239 
240             MavenReportExecutor mavenReportExecutor;
241             try
242             {
243                 mavenReportExecutor = (MavenReportExecutor) container.lookup( MavenReportExecutor.class.getName() );
244             }
245             catch ( ComponentLookupException e )
246             {
247                 throw new MojoExecutionException( "could not get MavenReportExecutor component", e );
248             }
249 
250             allReports = mavenReportExecutor.buildMavenReports( mavenReportExecutorRequest );
251         }
252         else
253         {
254             // Maven 2
255             allReports = new ArrayList<MavenReportExecution>( reports.size() );
256             for ( MavenReport report : reports )
257             {
258                 allReports.add( new MavenReportExecution( report ) );
259             }
260         }
261 
262         // filter out reports that can't be generated
263         List<MavenReportExecution> reportExecutions = new ArrayList<MavenReportExecution>( allReports.size() );
264         for ( MavenReportExecution exec : allReports )
265         {
266             if ( exec.canGenerateReport() )
267             {
268                 reportExecutions.add( exec );
269             }
270         }
271 
272         return reportExecutions;
273     }
274 
275     protected SiteRenderingContext createSiteRenderingContext( Locale locale )
276         throws MojoExecutionException, IOException, MojoFailureException
277     {
278         DecorationModel decorationModel = prepareDecorationModel( locale );
279         if ( attributes == null )
280         {
281             attributes = new HashMap<String, Object>();
282         }
283 
284         if ( attributes.get( "project" ) == null )
285         {
286             attributes.put( "project", project );
287         }
288 
289         if ( attributes.get( "inputEncoding" ) == null )
290         {
291             attributes.put( "inputEncoding", getInputEncoding() );
292         }
293 
294         if ( attributes.get( "outputEncoding" ) == null )
295         {
296             attributes.put( "outputEncoding", getOutputEncoding() );
297         }
298 
299         // Put any of the properties in directly into the Velocity context
300         for ( Map.Entry<Object, Object> entry : project.getProperties().entrySet() )
301         {
302             attributes.put( (String) entry.getKey(), entry.getValue() );
303         }
304 
305         SiteRenderingContext context;
306         if ( templateFile != null )
307         {
308             getLog().info( "Rendering site with " + templateFile + " template file." );
309 
310             if ( !templateFile.exists() )
311             {
312                 throw new MojoFailureException( "Template file '" + templateFile + "' does not exist" );
313             }
314             context = siteRenderer.createContextForTemplate( templateFile, attributes, decorationModel,
315                                                              project.getName(), locale );
316         }
317         else
318         {
319             try
320             {
321                 Artifact skinArtifact =
322                     siteTool.getSkinArtifactFromRepository( localRepository, repositories, decorationModel );
323 
324                 getLog().info( "Rendering site with " + skinArtifact.getId() + " skin." );
325 
326                 context = siteRenderer.createContextForSkin( skinArtifact, attributes, decorationModel,
327                                                              project.getName(), locale );
328             }
329             catch ( SiteToolException e )
330             {
331                 throw new MojoExecutionException( "SiteToolException while preparing skin: " + e.getMessage(), e );
332             }
333             catch ( RendererException e )
334             {
335                 throw new MojoExecutionException( "RendererException while preparing context for skin: "
336                     + e.getMessage(), e );
337             }
338         }
339 
340         // Generate static site
341         context.setRootDirectory( project.getBasedir() );
342         if ( !locale.getLanguage().equals( Locale.getDefault().getLanguage() ) )
343         {
344             context.addSiteDirectory( new File( siteDirectory, locale.getLanguage() ) );
345             context.addModuleDirectory( new File( xdocDirectory, locale.getLanguage() ), "xdoc" );
346             context.addModuleDirectory( new File( xdocDirectory, locale.getLanguage() ), "fml" );
347         }
348         else
349         {
350             context.addSiteDirectory( siteDirectory );
351             context.addModuleDirectory( xdocDirectory, "xdoc" );
352             context.addModuleDirectory( xdocDirectory, "fml" );
353         }
354 
355         if ( moduleExcludes != null )
356         {
357             context.setModuleExcludes( moduleExcludes );
358         }
359 
360         if ( saveProcessedContent )
361         {
362             context.setProcessedContentOutput( new File( generatedSiteDirectory, "processed" ) );
363         }
364 
365         return context;
366     }
367 
368     /**
369      * Go through the list of reports and process each one like this:
370      * <ul>
371      * <li>Add the report to a map of reports keyed by filename having the report itself as value
372      * <li>If the report is not yet in the map of documents, add it together with a suitable renderer
373      * </ul>
374      *
375      * @param reports A List of MavenReports
376      * @param documents A Map of documents, keyed by filename
377      * @param locale the Locale the reports are processed for.
378      * @return A map with all reports keyed by filename having the report itself as value.
379      * The map will be used to populate a menu.
380      */
381     protected Map<String, MavenReport> locateReports( List<MavenReportExecution> reports,
382                                                       Map<String, DocumentRenderer> documents, Locale locale )
383     {
384         // copy Collection to prevent ConcurrentModificationException
385         List<MavenReportExecution> filtered = new ArrayList<MavenReportExecution>( reports );
386 
387         Map<String, MavenReport> reportsByOutputName = new LinkedHashMap<String, MavenReport>();
388         for ( MavenReportExecution mavenReportExecution : filtered )
389         {
390             MavenReport report = mavenReportExecution.getMavenReport();
391 
392             String outputName = report.getOutputName() + ".html";
393 
394             // Always add the report to the menu, see MSITE-150
395             reportsByOutputName.put( report.getOutputName(), report );
396 
397             if ( documents.containsKey( outputName ) )
398             {
399                 String displayLanguage = locale.getDisplayLanguage( Locale.ENGLISH );
400 
401                 String reportMojoInfo =
402                     ( mavenReportExecution.getGoal() == null ) ? "" : ( " ("
403                         + mavenReportExecution.getPlugin().getArtifactId() + ':'
404                         + mavenReportExecution.getPlugin().getVersion() + ':' + mavenReportExecution.getGoal() + ')' );
405 
406                 getLog().info( "Skipped \"" + report.getName( locale ) + "\" report" + reportMojoInfo + ", file \""
407                                    + outputName + "\" already exists for the " + displayLanguage + " version." );
408 
409                 reports.remove( mavenReportExecution );
410             }
411             else
412             {
413                 String reportMojoInfo = mavenReportExecution.getPlugin().getGroupId() + ':'
414                     + mavenReportExecution.getPlugin().getArtifactId() + ':'
415                     + mavenReportExecution.getPlugin().getVersion() + ':' + mavenReportExecution.getGoal();
416                 RenderingContext renderingContext = new RenderingContext( siteDirectory, outputName, reportMojoInfo );
417                 DocumentRenderer renderer =
418                     new ReportDocumentRenderer( mavenReportExecution, renderingContext, getLog() );
419                 documents.put( outputName, renderer );
420             }
421         }
422         return reportsByOutputName;
423     }
424 
425     /**
426      * Go through the collection of reports and put each report into a list for the appropriate category. The list is
427      * put into a map keyed by the name of the category.
428      *
429      * @param reports A Collection of MavenReports
430      * @return A map keyed category having the report itself as value
431      */
432     protected Map<String, List<MavenReport>> categoriseReports( Collection<MavenReport> reports )
433     {
434         Map<String, List<MavenReport>> categories = new LinkedHashMap<String, List<MavenReport>>();
435         for ( MavenReport report : reports )
436         {
437             List<MavenReport> categoryReports = categories.get( report.getCategoryName() );
438             if ( categoryReports == null )
439             {
440                 categoryReports = new ArrayList<MavenReport>();
441                 categories.put( report.getCategoryName(), categoryReports );
442             }
443             categoryReports.add( report );
444         }
445         return categories;
446     }
447 
448     /**
449      * Locate every document to be rendered for given locale:<ul>
450      * <li>handwritten content, ie Doxia files,</li>
451      * <li>reports,</li>
452      * <li>"Project Information" and "Project Reports" category summaries.</li>
453      * </ul>
454      * @see CategorySummaryDocumentRenderer
455      */
456     protected Map<String, DocumentRenderer> locateDocuments( SiteRenderingContext context,
457                                                              List<MavenReportExecution> reports, Locale locale )
458         throws IOException, RendererException
459     {
460         Map<String, DocumentRenderer> documents = siteRenderer.locateDocumentFiles( context, true );
461 
462         Map<String, MavenReport> reportsByOutputName = locateReports( reports, documents, locale );
463 
464         // TODO: I want to get rid of categories eventually. There's no way to add your own in a fully i18n manner
465         Map<String, List<MavenReport>> categories = categoriseReports( reportsByOutputName.values() );
466 
467         siteTool.populateReportsMenu( context.getDecoration(), locale, categories );
468         populateReportItems( context.getDecoration(), locale, reportsByOutputName );
469 
470         if ( categories.containsKey( MavenReport.CATEGORY_PROJECT_INFORMATION ) && generateProjectInfo )
471         {
472             // add "Project Information" category summary document
473             List<MavenReport> categoryReports = categories.get( MavenReport.CATEGORY_PROJECT_INFORMATION );
474 
475             RenderingContext renderingContext =
476                 new RenderingContext( siteDirectory, "project-info.html",
477                                       getSitePluginInfo() + ":CategorySummaryDocumentRenderer" );
478             String title = i18n.getString( "site-plugin", locale, "report.information.title" );
479             String desc1 = i18n.getString( "site-plugin", locale, "report.information.description1" );
480             String desc2 = i18n.getString( "site-plugin", locale, "report.information.description2" );
481             DocumentRenderer renderer = new CategorySummaryDocumentRenderer( renderingContext, title, desc1, desc2,
482                                                                              i18n, categoryReports, getLog() );
483 
484             if ( !documents.containsKey( renderer.getOutputName() ) )
485             {
486                 documents.put( renderer.getOutputName(), renderer );
487             }
488             else
489             {
490                 getLog().info( "Category summary '" + renderer.getOutputName() + "' skipped; already exists" );
491             }
492         }
493 
494         if ( categories.containsKey( MavenReport.CATEGORY_PROJECT_REPORTS ) )
495         {
496             // add "Project Reports" category summary document
497             List<MavenReport> categoryReports = categories.get( MavenReport.CATEGORY_PROJECT_REPORTS );
498             RenderingContext renderingContext =
499                 new RenderingContext( siteDirectory, "project-reports.html",
500                                       getSitePluginInfo() + ":CategorySummaryDocumentRenderer" );
501             String title = i18n.getString( "site-plugin", locale, "report.project.title" );
502             String desc1 = i18n.getString( "site-plugin", locale, "report.project.description1" );
503             String desc2 = i18n.getString( "site-plugin", locale, "report.project.description2" );
504             DocumentRenderer renderer = new CategorySummaryDocumentRenderer( renderingContext, title, desc1, desc2,
505                                                                              i18n, categoryReports, getLog() );
506 
507             if ( !documents.containsKey( renderer.getOutputName() ) )
508             {
509                 documents.put( renderer.getOutputName(), renderer );
510             }
511             else
512             {
513                 getLog().info( "Category summary '" + renderer.getOutputName() + "' skipped; already exists" );
514             }
515         }
516         return documents;
517     }
518 
519     private String getSitePluginInfo()
520     {
521         PluginDescriptor pluginDescriptor = (PluginDescriptor) getPluginContext().get( "pluginDescriptor" );
522         return pluginDescriptor.getId();
523     }
524     protected void populateReportItems( DecorationModel decorationModel, Locale locale,
525                                         Map<String, MavenReport> reportsByOutputName )
526     {
527         for ( Menu menu : decorationModel.getMenus() )
528         {
529             populateItemRefs( menu.getItems(), locale, reportsByOutputName );
530         }
531     }
532 
533     private void populateItemRefs( List<MenuItem> items, Locale locale, Map<String, MavenReport> reportsByOutputName )
534     {
535         for ( Iterator<MenuItem> i = items.iterator(); i.hasNext(); )
536         {
537             MenuItem item = i.next();
538 
539             if ( item.getRef() != null )
540             {
541                 MavenReport report = reportsByOutputName.get( item.getRef() );
542 
543                 if ( report != null )
544                 {
545                     if ( item.getName() == null )
546                     {
547                         item.setName( report.getName( locale ) );
548                     }
549 
550                     if ( item.getHref() == null || item.getHref().length() == 0 )
551                     {
552                         item.setHref( report.getOutputName() + ".html" );
553                     }
554                 }
555                 else
556                 {
557                     getLog().warn( "Unrecognised reference: '" + item.getRef() + "'" );
558                     i.remove();
559                 }
560             }
561 
562             populateItemRefs( item.getItems(), locale, reportsByOutputName );
563         }
564     }
565 }