View Javadoc

1   package org.apache.maven.plugins.site;
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 org.apache.maven.artifact.factory.ArtifactFactory;
23  import org.apache.maven.artifact.repository.ArtifactRepository;
24  import org.apache.maven.artifact.resolver.ArtifactResolver;
25  import org.apache.maven.doxia.sink.render.RenderingContext;
26  import org.apache.maven.doxia.site.decoration.DecorationModel;
27  import org.apache.maven.doxia.site.decoration.inheritance.DecorationModelInheritanceAssembler;
28  import org.apache.maven.doxia.siterenderer.DocumentRenderer;
29  import org.apache.maven.doxia.siterenderer.Renderer;
30  import org.apache.maven.doxia.siterenderer.RendererException;
31  import org.apache.maven.doxia.siterenderer.SiteRenderingContext;
32  import org.apache.maven.doxia.tools.SiteToolException;
33  import org.apache.maven.plugin.MojoExecutionException;
34  import org.apache.maven.plugin.MojoFailureException;
35  import org.apache.maven.reporting.MavenReport;
36  
37  import java.io.File;
38  import java.io.IOException;
39  import java.util.ArrayList;
40  import java.util.Collection;
41  import java.util.HashMap;
42  import java.util.Iterator;
43  import java.util.List;
44  import java.util.Locale;
45  import java.util.Map;
46  
47  /**
48   * Base class for site rendering mojos.
49   *
50   * @author <a href="mailto:brett@apache.org">Brett Porter</a>
51   * @version $Id: AbstractSiteRenderingMojo.html 816556 2012-05-08 11:58:34Z hboutemy $
52   */
53  public abstract class AbstractSiteRenderingMojo
54      extends AbstractSiteMojo
55  {
56      /**
57       * Module type exclusion mappings
58       * ex: <code>fml  -> **&#47;*-m1.fml</code>  (excludes fml files ending in '-m1.fml' recursively)
59       * <p/>
60       * The configuration looks like this:
61       * <pre>
62       *   &lt;moduleExcludes&gt;
63       *     &lt;moduleType&gt;filename1.ext,**&#47;*sample.ext&lt;/moduleType&gt;
64       *     &lt;!-- moduleType can be one of 'apt', 'fml' or 'xdoc'. --&gt;
65       *     &lt;!-- The value is a comma separated list of           --&gt;
66       *     &lt;!-- filenames or fileset patterns.                   --&gt;
67       *     &lt;!-- Here's an example:                               --&gt;
68       *     &lt;xdoc&gt;changes.xml,navigation.xml&lt;/xdoc&gt;
69       *   &lt;/moduleExcludes&gt;
70       * </pre>
71       *
72       * @parameter
73       */
74      protected Map<String, String> moduleExcludes;
75  
76      /**
77       * The component for assembling inheritance.
78       *
79       * @component
80       */
81      protected DecorationModelInheritanceAssembler assembler;
82  
83      /**
84       * The component that is used to resolve additional artifacts required.
85       *
86       * @component
87       */
88      protected ArtifactResolver artifactResolver;
89  
90      /**
91       * Remote repositories used for the project.
92       *
93       * @todo this is used for site descriptor resolution - it should relate to the actual project but for some reason they are not always filled in
94       * @parameter expression="${project.remoteArtifactRepositories}"
95       */
96      protected List<ArtifactRepository> repositories;
97  
98      /**
99       * The component used for creating artifact instances.
100      *
101      * @component
102      */
103     protected ArtifactFactory artifactFactory;
104 
105     /**
106      * Directory containing the template page.
107      *
108      * @parameter expression="${templateDirectory}" default-value="src/site"
109      * @deprecated use templateFile or skinning instead
110      */
111     private File templateDirectory;
112 
113     /**
114      * Default template page.
115      *
116      * @parameter expression="${template}"
117      * @deprecated use templateFile or skinning instead
118      */
119     private String template;
120 
121     /**
122      * The location of a Velocity template file to use. When used, skins and the default templates, CSS and images
123      * are disabled. It is highly recommended that you package this as a skin instead.
124      *
125      * @parameter expression="${templateFile}"
126      * @since 2.0-beta-5
127      */
128     private File templateFile;
129 
130     /**
131      * The template properties for rendering the site.
132      *
133      * @parameter expression="${attributes}"
134      */
135     protected Map<Object, Object> attributes;
136 
137     /**
138      * Site renderer.
139      *
140      * @component
141      */
142     protected Renderer siteRenderer;
143 
144     /**
145      * @parameter expression="${reports}"
146      * @required
147      * @readonly
148      */
149     protected List<MavenReport> reports;
150 
151     /**
152      * Alternative directory for xdoc source, useful for m1 to m2 migration
153      *
154      * @parameter default-value="${basedir}/xdocs"
155      * @deprecated use the standard m2 directory layout
156      */
157     private File xdocDirectory;
158 
159     /**
160      * Directory containing generated documentation.
161      *
162      * @parameter alias="workingDirectory" expression="${project.build.directory}/generated-site"
163      * @required
164      * @todo should we deprecate in favour of reports?
165      */
166     protected File generatedSiteDirectory;
167 
168     protected List<MavenReport> filterReports( List<MavenReport> reports )
169     {
170         List<MavenReport> filteredReports = new ArrayList<MavenReport>( reports.size() );
171         for ( MavenReport report : reports )
172         {
173             //noinspection ErrorNotRethrown,UnusedCatchParameter
174             try
175             {
176                 if ( report.canGenerateReport() )
177                 {
178                     filteredReports.add( report );
179                 }
180             }
181             catch ( AbstractMethodError e )
182             {
183                 // the canGenerateReport() has been added just before the 2.0 release and will cause all the reporting
184                 // plugins with an earlier version to fail (most of the org.codehaus mojo now fails)
185                 // be nice with them, output a warning and don't let them break anything
186 
187                 getLog().warn(
188                                "Error loading report " + report.getClass().getName()
189                                    + " - AbstractMethodError: canGenerateReport()" );
190                 filteredReports.add( report );
191             }
192         }
193         return filteredReports;
194     }
195 
196     protected SiteRenderingContext createSiteRenderingContext( Locale locale )
197         throws MojoExecutionException, IOException, MojoFailureException
198     {
199         if ( attributes == null )
200         {
201             attributes = new HashMap<Object, Object>();
202         }
203 
204         if ( attributes.get( "project" ) == null )
205         {
206             attributes.put( "project", project );
207         }
208 
209         if ( attributes.get( "inputEncoding" ) == null )
210         {
211             attributes.put( "inputEncoding", getInputEncoding() );
212         }
213 
214         if ( attributes.get( "outputEncoding" ) == null )
215         {
216             attributes.put( "outputEncoding", getOutputEncoding() );
217         }
218 
219         // Put any of the properties in directly into the Velocity context
220         attributes.putAll( project.getProperties() );
221 
222         DecorationModel decorationModel;
223         try
224         {
225             decorationModel = siteTool.getDecorationModel( project, reactorProjects, localRepository, repositories,
226                                                            toRelative( project.getBasedir(),
227                                                                        siteDirectory.getAbsolutePath() ),
228                                                            locale, getInputEncoding(), getOutputEncoding() );
229         }
230         catch ( SiteToolException e )
231         {
232             throw new MojoExecutionException( "SiteToolException: " + e.getMessage(), e );
233         }
234         if ( template != null )
235         {
236             if ( templateFile != null )
237             {
238                 getLog().warn( "'template' configuration is ignored when 'templateFile' is set" );
239             }
240             else
241             {
242                 templateFile = new File( templateDirectory, template );
243             }
244         }
245 
246         File skinFile;
247         try
248         {
249             skinFile = siteTool.getSkinArtifactFromRepository( localRepository, repositories, decorationModel )
250                 .getFile();
251         }
252         catch ( SiteToolException e )
253         {
254             throw new MojoExecutionException( "SiteToolException: " + e.getMessage(), e );
255         }
256         SiteRenderingContext context;
257         if ( templateFile != null )
258         {
259             if ( !templateFile.exists() )
260             {
261                 throw new MojoFailureException( "Template file '" + templateFile + "' does not exist" );
262             }
263             context = siteRenderer.createContextForTemplate( templateFile, skinFile, attributes, decorationModel,
264                                                              project.getName(), locale );
265         }
266         else
267         {
268             context = siteRenderer.createContextForSkin( skinFile, attributes, decorationModel, project.getName(),
269                                                          locale );
270         }
271 
272         // Generate static site
273         if ( !locale.getLanguage().equals( Locale.getDefault().getLanguage() ) )
274         {
275             context.addSiteDirectory( new File( siteDirectory, locale.getLanguage() ) );
276             context.addModuleDirectory( new File( xdocDirectory, locale.getLanguage() ), "xdoc" );
277             context.addModuleDirectory( new File( xdocDirectory, locale.getLanguage() ), "fml" );
278         }
279         else
280         {
281             context.addSiteDirectory( siteDirectory );
282             context.addModuleDirectory( xdocDirectory, "xdoc" );
283             context.addModuleDirectory( xdocDirectory, "fml" );
284         }
285 
286         if ( moduleExcludes != null )
287         {
288             context.setModuleExcludes( moduleExcludes );
289         }
290 
291         return context;
292     }
293 
294     /**
295      * Go through the list of reports and process each one like this:
296      * <ul>
297      * <li>Add the report to a map of reports keyed by filename having the report itself as value
298      * <li>If the report is not yet in the map of documents, add it together with a suitable renderer
299      * </ul>
300      *
301      * @param reports A List of MavenReports
302      * @param documents A Map of documents, keyed by filename
303      * @param locale the Locale the reports are processed for.
304      * @return A map with all reports keyed by filename having the report itself as value.
305      * The map will be used to populate a menu.
306      */
307     protected Map<String, MavenReport> locateReports( List<MavenReport> reports,
308                                                       Map<String, DocumentRenderer> documents, Locale locale )
309     {
310         Map<String, MavenReport> reportsByOutputName = new HashMap<String, MavenReport>();
311         for ( Iterator<MavenReport> i = reports.iterator(); i.hasNext(); )
312         {
313             MavenReport report = i.next();
314 
315             String outputName = report.getOutputName() + ".html";
316 
317             // Always add the report to the menu, see MSITE-150
318             reportsByOutputName.put( report.getOutputName(), report );
319 
320             if ( documents.containsKey( outputName ) )
321             {
322                 String displayLanguage = locale.getDisplayLanguage( Locale.ENGLISH );
323 
324                 getLog().info( "Skipped \"" + report.getName( locale ) + "\" report, file \"" + outputName
325                                    + "\" already exists for the " + displayLanguage + " version." );
326                 i.remove();
327             }
328             else
329             {
330                 RenderingContext renderingContext = new RenderingContext( siteDirectory, outputName );
331                 ReportDocumentRenderer renderer = new ReportDocumentRenderer( report, renderingContext, getLog() );
332                 documents.put( outputName, renderer );
333             }
334         }
335         return reportsByOutputName;
336     }
337 
338     /**
339      * Go through the collection of reports and put each report into a list for the appropriate category. The list is
340      * put into a map keyed by the name of the category.
341      *
342      * @param reports A Collection of MavenReports
343      * @return A map keyed category having the report itself as value
344      */
345     protected Map<String, List<MavenReport>> categoriseReports( Collection<MavenReport> reports )
346     {
347         Map<String, List<MavenReport>> categories = new HashMap<String, List<MavenReport>>();
348         for ( MavenReport report : reports )
349         {
350             List<MavenReport> categoryReports = categories.get( report.getCategoryName() );
351             if ( categoryReports == null )
352             {
353                 categoryReports = new ArrayList<MavenReport>();
354                 categories.put( report.getCategoryName(), categoryReports );
355             }
356             categoryReports.add( report );
357         }
358         return categories;
359     }
360 
361     protected Map<String, DocumentRenderer> locateDocuments( SiteRenderingContext context, List<MavenReport> reports,
362                                                              Locale locale )
363         throws IOException, RendererException
364     {
365         Map<String, DocumentRenderer> documents = siteRenderer.locateDocumentFiles( context );
366 
367         Map<String, MavenReport> reportsByOutputName = locateReports( reports, documents, locale );
368 
369         // TODO: I want to get rid of categories eventually. There's no way to add your own in a fully i18n manner
370         Map<String, List<MavenReport>> categories = categoriseReports( reportsByOutputName.values() );
371 
372         siteTool.populateReportsMenu( context.getDecoration(), locale, categories );
373         populateReportItems( context.getDecoration(), locale, reportsByOutputName );
374 
375         if ( categories.containsKey( MavenReport.CATEGORY_PROJECT_INFORMATION ) )
376         {
377             List<MavenReport> categoryReports = categories.get( MavenReport.CATEGORY_PROJECT_INFORMATION );
378 
379             RenderingContext renderingContext = new RenderingContext( siteDirectory, "project-info.html" );
380             String title = i18n.getString( "site-plugin", locale, "report.information.title" );
381             String desc1 = i18n.getString( "site-plugin", locale, "report.information.description1" );
382             String desc2 = i18n.getString( "site-plugin", locale, "report.information.description2" );
383             DocumentRenderer renderer = new CategorySummaryDocumentRenderer( renderingContext, title, desc1, desc2,
384                                                                              i18n, categoryReports, getLog() );
385 
386             if ( !documents.containsKey( renderer.getOutputName() ) )
387             {
388                 documents.put( renderer.getOutputName(), renderer );
389             }
390             else
391             {
392                 getLog().info( "Category summary '" + renderer.getOutputName() + "' skipped; already exists" );
393             }
394         }
395 
396         if ( categories.containsKey( MavenReport.CATEGORY_PROJECT_REPORTS ) )
397         {
398             List<MavenReport> categoryReports = categories.get( MavenReport.CATEGORY_PROJECT_REPORTS );
399             RenderingContext renderingContext = new RenderingContext( siteDirectory, "project-reports.html" );
400             String title = i18n.getString( "site-plugin", locale, "report.project.title" );
401             String desc1 = i18n.getString( "site-plugin", locale, "report.project.description1" );
402             String desc2 = i18n.getString( "site-plugin", locale, "report.project.description2" );
403             DocumentRenderer renderer = new CategorySummaryDocumentRenderer( renderingContext, title, desc1, desc2,
404                                                                              i18n, categoryReports, getLog() );
405 
406             if ( !documents.containsKey( renderer.getOutputName() ) )
407             {
408                 documents.put( renderer.getOutputName(), renderer );
409             }
410             else
411             {
412                 getLog().info( "Category summary '" + renderer.getOutputName() + "' skipped; already exists" );
413             }
414         }
415         return documents;
416     }
417 }