View Javadoc
1   package org.apache.maven.plugin.changes;
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.FileWriter;
24  import java.io.IOException;
25  import java.io.Writer;
26  import java.net.URL;
27  import java.text.SimpleDateFormat;
28  import java.util.Collections;
29  import java.util.Date;
30  import java.util.List;
31  import java.util.Locale;
32  import java.util.Map;
33  import java.util.Map.Entry;
34  import java.util.Properties;
35  import java.util.ResourceBundle;
36  
37  import org.apache.commons.collections.map.CaseInsensitiveMap;
38  import org.apache.commons.io.input.XmlStreamReader;
39  import org.apache.maven.execution.MavenSession;
40  import org.apache.maven.plugins.annotations.Component;
41  import org.apache.maven.plugins.annotations.Mojo;
42  import org.apache.maven.plugins.annotations.Parameter;
43  import org.apache.maven.plugins.changes.model.Release;
44  import org.apache.maven.project.MavenProject;
45  import org.apache.maven.reporting.MavenReportException;
46  import org.apache.maven.shared.filtering.MavenFileFilter;
47  import org.apache.maven.shared.filtering.MavenFileFilterRequest;
48  import org.apache.maven.shared.filtering.MavenFilteringException;
49  import org.codehaus.plexus.util.FileUtils;
50  import org.codehaus.plexus.util.IOUtil;
51  import org.codehaus.plexus.util.StringUtils;
52  
53  /**
54   * Goal which creates a nicely formatted Changes Report in html format from a changes.xml file.
55   *
56   * @author <a href="mailto:jruiz@exist.com">Johnny R. Ruiz III</a>
57   * @version $Id: ChangesMojo.java 1685894 2015-06-16 19:29:09Z khmarbaise $
58   */
59  @Mojo( name = "changes-report", threadSafe = true )
60  public class ChangesMojo
61      extends AbstractChangesReport
62  {
63      /**
64       * A flag whether the report should also include changes from child modules. If set to <code>false</code>, only the
65       * changes from current project will be written to the report.
66       *
67       * @since 2.5
68       */
69      @Parameter( defaultValue = "false" )
70      private boolean aggregated;
71  
72      /**
73       * A flag whether the report should also include the dates of individual actions. If set to <code>false</code>, only
74       * the dates of releases will be written to the report.
75       *
76       * @since 2.1
77       */
78      @Parameter( property = "changes.addActionDate", defaultValue = "false" )
79      private boolean addActionDate;
80  
81      /**
82       * Whether HTML code within an action should be escaped. By changing this to <code>false</code> you can restore the
83       * behavior that was in version 2.2 of this plugin, allowing you to use HTML code to format the content of an
84       * action.
85       * <p>
86       * <strong>Note:</strong> If you use HTML code in an action you need to place it inside a CDATA section.
87       * </p>
88       * <strong>Note:</strong> Putting any kind of markup inside a CDATA section might mess up the Changes Report or
89       * other generated documents, such as PDFs, that are based on your <code>changes.xml</code> file if you are not
90       * careful.
91       *
92       * @since 2.4
93       * @deprecated using markup inside CDATA sections does not work for all output formats!
94       */
95      @Parameter( defaultValue = "true" )
96      private boolean escapeHTML;
97  
98      /**
99       * The directory for interpolated changes.xml.
100      *
101      * @since 2.2
102      */
103     @Parameter( defaultValue = "${project.build.directory}/changes", required = true, readonly = true )
104     private File filteredOutputDirectory;
105 
106     /**
107      * applying filtering filtering "a la" resources plugin
108      *
109      * @since 2.2
110      */
111     @Parameter( defaultValue = "false" )
112     private boolean filteringChanges;
113 
114     /**
115      * Template string that is used to discover the URL to use to display an issue report. There are 2 template tokens
116      * you can use. <code>%URL%</code>: this is computed by getting the <code>&lt;issueManagement&gt;/&lt;url&gt;</code>
117      * value from the POM, and removing the last '/' and everything that comes after it. <code>%ISSUE%</code>: this is
118      * the issue number.
119      * <p>
120      * <strong>Note:</strong> In versions of this plugin prior to 2.0-beta-2 this parameter was called
121      * <code>link_template</code>.
122      * </p>
123      *
124      * @since 2.0-beta-2
125      * @deprecated As of 2.1 use issueLinkTemplatePerSystem : this one will be with system default
126      */
127     @Parameter( property = "changes.issueLinkTemplate", defaultValue = "%URL%/ViewIssue.jspa?key=%ISSUE%" )
128     private String issueLinkTemplate;
129 
130     /**
131      * Template strings per system that is used to discover the URL to use to display an issue report. Each key in this
132      * map denotes the (case-insensitive) identifier of the issue tracking system and its value gives the URL template.
133      * <p>
134      * There are 2 template tokens you can use. <code>%URL%</code>: this is computed by getting the
135      * <code>&lt;issueManagement&gt;/&lt;url&gt;</code> value from the POM, and removing the last '/' and everything
136      * that comes after it. <code>%ISSUE%</code>: this is the issue number.
137      * </p>
138      * <p>
139      * <strong>Note:</strong> The deprecated issueLinkTemplate will be used for a system called "default".
140      * </p>
141      * <p>
142      * <strong>Note:</strong> Starting with version 2.4 you usually don't need to specify this, unless you need to link
143      * to an issue management system in your Changes report that isn't supported out of the box. See the
144      * <a href="./usage.html">Usage page</a> for more information.
145      * </p>
146      *
147      * @since 2.1
148      */
149     @Parameter
150     private Map<String, String> issueLinkTemplatePerSystem;
151 
152     /**
153      * @since 2.2
154      */
155     @Component
156     private MavenFileFilter mavenFileFilter;
157 
158     /**
159      * Format to use for publishDate. The value will be available with the following expression ${publishDate}
160      *
161      * @see java.text.SimpleDateFormat
162      * @since 2.2
163      */
164     @Parameter( defaultValue = "yyyy-MM-dd" )
165     private String publishDateFormat;
166 
167     /**
168      * Locale to use for publishDate when formatting
169      *
170      * @see java.util.Locale
171      * @since 2.2
172      */
173     @Parameter( defaultValue = "en" )
174     private String publishDateLocale;
175 
176     /**
177      * @since 2.2
178      */
179     @Parameter( defaultValue = "${session}", readonly = true, required = true )
180     protected MavenSession session;
181 
182     /**
183      * @since 2.4
184      */
185     @Parameter( defaultValue = "${project.issueManagement.system}", readonly = true )
186     private String system;
187 
188     /**
189      * The URI of a file containing all the team members. If this is set to the special value "none", no links will be
190      * generated for the team members.
191      *
192      * @since 2.4
193      */
194     @Parameter( defaultValue = "team-list.html" )
195     private String teamlist;
196 
197     /**
198      */
199     @Parameter( defaultValue = "${project.issueManagement.url}", readonly = true )
200     private String url;
201 
202     /**
203      * The type of the feed to generate.
204      * <p>
205      * Supported values are: <code>"rss_0.9", "rss_0.91N" (RSS 0.91 Netscape), "rss_0.91U" (RSS 0.91 Userland),
206      * "rss_0.92", "rss_0.93", "rss_0.94", "rss_1.0", "rss_2.0", "atom_0.3", "atom_1.0"</code>.
207      * </p>
208      * <p>
209      * If not specified, no feed is generated.
210      * </p>
211      *
212      * @since 2.9
213      */
214     @Parameter
215     private String feedType;
216 
217     /**
218      * The path of the <code>changes.xml</code> file that will be converted into an HTML report.
219      */
220     @Parameter( property = "changes.xmlPath", defaultValue = "src/changes/changes.xml" )
221     private File xmlPath;
222 
223     private ReleaseUtils releaseUtils = new ReleaseUtils( getLog() );
224 
225     private CaseInsensitiveMap caseInsensitiveIssueLinkTemplatePerSystem;
226 
227     /* --------------------------------------------------------------------- */
228     /* Public methods */
229     /* --------------------------------------------------------------------- */
230 
231     public boolean canGenerateReport()
232     {
233         // Run only at the execution root
234         if ( runOnlyAtExecutionRoot && !isThisTheExecutionRoot() )
235         {
236             getLog().info( "Skipping the Changes Report in this project because it's not the Execution Root" );
237             return false;
238         }
239         return xmlPath.isFile();
240     }
241 
242     public void executeReport( Locale locale )
243         throws MavenReportException
244     {
245         Date now = new Date();
246         SimpleDateFormat simpleDateFormat = new SimpleDateFormat( publishDateFormat, new Locale( publishDateLocale ) );
247         Properties additionalProperties = new Properties();
248         additionalProperties.put( "publishDate", simpleDateFormat.format( now ) );
249 
250         ChangesXML changesXml = getChangesFromFile( xmlPath, project, additionalProperties );
251         if ( changesXml == null )
252         {
253             return;
254         }
255 
256         if ( aggregated )
257         {
258             final String basePath = project.getBasedir().getAbsolutePath();
259             final String absolutePath = xmlPath.getAbsolutePath();
260             if ( !absolutePath.startsWith( basePath ) )
261             {
262                 getLog().warn( "xmlPath should be within the project dir for aggregated changes report." );
263                 return;
264             }
265             final String relativePath = absolutePath.substring( basePath.length() );
266 
267             List<Release> releaseList = changesXml.getReleaseList();
268             for ( Object o : project.getCollectedProjects() )
269             {
270                 final MavenProject childProject = (MavenProject) o;
271                 final File changesFile = new File( childProject.getBasedir(), relativePath );
272                 final ChangesXML childXml = getChangesFromFile( changesFile, childProject, additionalProperties );
273                 if ( childXml != null )
274                 {
275                     releaseList =
276                         releaseUtils.mergeReleases( releaseList, childProject.getName(), childXml.getReleaseList() );
277                 }
278             }
279             changesXml.setReleaseList( releaseList );
280         }
281 
282         ChangesReportGenerator report = new ChangesReportGenerator( changesXml.getReleaseList() );
283 
284         report.setAuthor( changesXml.getAuthor() );
285         report.setTitle( changesXml.getTitle() );
286 
287         report.setEscapeHTML( escapeHTML );
288 
289         // Create a case insensitive version of issueLinkTemplatePerSystem
290         // We need something case insensitive to maintain backward compatibility
291         if ( issueLinkTemplatePerSystem == null )
292         {
293             caseInsensitiveIssueLinkTemplatePerSystem = new CaseInsensitiveMap();
294         }
295         else
296         {
297             caseInsensitiveIssueLinkTemplatePerSystem = new CaseInsensitiveMap( issueLinkTemplatePerSystem );
298         }
299 
300         // Set good default values for issue management systems here, but only
301         // if they have not been configured already by the user
302         addIssueLinkTemplate( ChangesReportGenerator.DEFAULT_ISSUE_SYSTEM_KEY, issueLinkTemplate );
303         addIssueLinkTemplate( "Bitbucket", "%URL%/issue/%ISSUE%" );
304         addIssueLinkTemplate( "Bugzilla", "%URL%/show_bug.cgi?id=%ISSUE%" );
305         addIssueLinkTemplate( "GitHub", "%URL%/%ISSUE%" );
306         addIssueLinkTemplate( "GoogleCode", "%URL%/detail?id=%ISSUE%" );
307         addIssueLinkTemplate( "JIRA", "%URL%/%ISSUE%" );
308         addIssueLinkTemplate( "Mantis", "%URL%/view.php?id=%ISSUE%" );
309         addIssueLinkTemplate( "MKS", "%URL%/viewissue?selection=%ISSUE%" );
310         addIssueLinkTemplate( "Redmine", "%URL%/issues/show/%ISSUE%" );
311         addIssueLinkTemplate( "Scarab", "%URL%/issues/id/%ISSUE%" );
312         addIssueLinkTemplate( "SourceForge", "http://sourceforge.net/support/tracker.php?aid=%ISSUE%" );
313         addIssueLinkTemplate( "SourceForge2", "%URL%/%ISSUE%" );
314         addIssueLinkTemplate( "Trac", "%URL%/ticket/%ISSUE%" );
315         addIssueLinkTemplate( "Trackplus", "%URL%/printItem.action?key=%ISSUE%" );
316         addIssueLinkTemplate( "YouTrack", "%URL%/issue/%ISSUE%" );
317         // @todo Add more issue management systems here
318         // Remember to also add documentation in usage.apt.vm
319 
320         // Show the current issueLinkTemplatePerSystem configuration
321         logIssueLinkTemplatePerSystem( caseInsensitiveIssueLinkTemplatePerSystem );
322 
323         report.setIssueLinksPerSystem( caseInsensitiveIssueLinkTemplatePerSystem );
324 
325         report.setSystem( system );
326 
327         report.setTeamlist( teamlist );
328 
329         report.setUrl( url );
330 
331         report.setAddActionDate( addActionDate );
332 
333         if ( StringUtils.isEmpty( url ) )
334         {
335             getLog().warn( "No issue management URL defined in POM. Links to your issues will not work correctly." );
336         }
337 
338         boolean feedGenerated = false;
339 
340         if ( StringUtils.isNotEmpty( feedType ) )
341         {
342             feedGenerated = generateFeed( changesXml, locale );
343         }
344 
345         report.setLinkToFeed( feedGenerated );
346 
347         report.doGenerateReport( getBundle( locale ), getSink() );
348 
349         // Copy the images
350         copyStaticResources();
351     }
352 
353     public String getDescription( Locale locale )
354     {
355         return getBundle( locale ).getString( "report.issues.description" );
356     }
357 
358     public String getName( Locale locale )
359     {
360         return getBundle( locale ).getString( "report.issues.name" );
361     }
362 
363     public String getOutputName()
364     {
365         return "changes-report";
366     }
367 
368     /* --------------------------------------------------------------------- */
369     /* Private methods */
370     /* --------------------------------------------------------------------- */
371 
372     /**
373      * Parses specified changes.xml file. It also makes filtering if needed. If specified file doesn't exist it will log
374      * warning and return <code>null</code>.
375      *
376      * @param changesXml changes xml file to parse
377      * @param project maven project to parse changes for
378      * @param additionalProperties additional properties used for filtering
379      * @return parsed <code>ChangesXML</code> instance or null if file doesn't exist
380      * @throws MavenReportException if any errors occurs while parsing
381      */
382     private ChangesXML getChangesFromFile( File changesXml, MavenProject project, Properties additionalProperties )
383         throws MavenReportException
384     {
385         if ( !changesXml.exists() )
386         {
387             getLog().warn( "changes.xml file " + changesXml.getAbsolutePath() + " does not exist." );
388             return null;
389         }
390 
391         if ( filteringChanges )
392         {
393             if ( !filteredOutputDirectory.exists() )
394             {
395                 filteredOutputDirectory.mkdirs();
396             }
397             XmlStreamReader xmlStreamReader = null;
398             try
399             {
400                 // so we get encoding from the file itself
401                 xmlStreamReader = new XmlStreamReader( changesXml );
402                 String encoding = xmlStreamReader.getEncoding();
403                 File resultFile = new File( filteredOutputDirectory,
404                                             project.getGroupId() + "." + project.getArtifactId() + "-changes.xml" );
405 
406                 final MavenFileFilterRequest mavenFileFilterRequest =
407                     new MavenFileFilterRequest( changesXml, resultFile, true, project, Collections.<String>emptyList(),
408                                                 false, encoding, session, additionalProperties );
409                 mavenFileFilter.copyFile( mavenFileFilterRequest );
410                 changesXml = resultFile;
411             }
412             catch ( IOException e )
413             {
414                 throw new MavenReportException( "Exception during filtering changes file : " + e.getMessage(), e );
415             }
416             catch ( MavenFilteringException e )
417             {
418                 throw new MavenReportException( "Exception during filtering changes file : " + e.getMessage(), e );
419             }
420             finally
421             {
422                 if ( xmlStreamReader != null )
423                 {
424                     IOUtil.close( xmlStreamReader );
425                 }
426             }
427 
428         }
429         return new ChangesXML( changesXml, getLog() );
430     }
431 
432     /**
433      * Add the issue link template for the given issue management system, but only if it has not already been
434      * configured.
435      *
436      * @param system The issue management system
437      * @param issueLinkTemplate The issue link template to use
438      * @since 2.4
439      */
440     private void addIssueLinkTemplate( String system, String issueLinkTemplate )
441     {
442         if ( caseInsensitiveIssueLinkTemplatePerSystem == null )
443         {
444             caseInsensitiveIssueLinkTemplatePerSystem = new CaseInsensitiveMap();
445         }
446         if ( !caseInsensitiveIssueLinkTemplatePerSystem.containsKey( system ) )
447         {
448             caseInsensitiveIssueLinkTemplatePerSystem.put( system, issueLinkTemplate );
449         }
450     }
451 
452     private void copyStaticResources()
453         throws MavenReportException
454     {
455         final String pluginResourcesBase = "org/apache/maven/plugin/changes";
456         String resourceNames[] = { "images/add.gif", "images/fix.gif", "images/icon_help_sml.gif", "images/remove.gif",
457             "images/rss.png", "images/update.gif" };
458         try
459         {
460             getLog().debug( "Copying static resources." );
461             for ( String resourceName : resourceNames )
462             {
463                 URL url = this.getClass().getClassLoader().getResource( pluginResourcesBase + "/" + resourceName );
464                 FileUtils.copyURLToFile( url, new File( getReportOutputDirectory(), resourceName ) );
465             }
466         }
467         catch ( IOException e )
468         {
469             throw new MavenReportException( "Unable to copy static resources." );
470         }
471     }
472 
473     private ResourceBundle getBundle( Locale locale )
474     {
475         return ResourceBundle.getBundle( "changes-report", locale, this.getClass().getClassLoader() );
476     }
477 
478     protected String getTeamlist()
479     {
480         return teamlist;
481     }
482 
483     private void logIssueLinkTemplatePerSystem( Map<String, String> issueLinkTemplatePerSystem )
484     {
485         if ( getLog().isDebugEnabled() )
486         {
487             if ( issueLinkTemplatePerSystem == null )
488             {
489                 getLog().debug( "No issueLinkTemplatePerSystem configuration was found" );
490             }
491             else
492             {
493                 for ( Entry<String, String> entry : issueLinkTemplatePerSystem.entrySet() )
494                 {
495                     getLog().debug( "issueLinkTemplatePerSystem[" + entry.getKey() + "] = " + entry.getValue() );
496                 }
497             }
498         }
499     }
500 
501     private boolean generateFeed( final ChangesXML changesXml, final Locale locale )
502     {
503         getLog().debug( "Generating " + feedType + " feed." );
504 
505         boolean success = true;
506 
507         final FeedGenerator feed = new FeedGenerator( locale );
508         feed.setLink( project.getUrl() + "/changes-report.html" ); // TODO: better way?
509         feed.setTitle( project.getName() + ": " + changesXml.getTitle() );
510         feed.setAuthor( changesXml.getAuthor() );
511         feed.setDateFormat( new SimpleDateFormat( publishDateFormat, new Locale( publishDateLocale ) ) );
512 
513         Writer writer = null;
514 
515         try
516         {
517             writer = new FileWriter( new File( getReportOutputDirectory(), "changes.rss" ) );
518             feed.export( changesXml.getReleaseList(), feedType, writer );
519         }
520         catch ( IOException ex )
521         {
522             success = false;
523             getLog().warn( "Failed to create rss feed: " + ex.getMessage() );
524             getLog().debug( ex );
525         }
526         finally
527         {
528             try
529             {
530                 if ( writer != null )
531                 {
532                     writer.close();
533                 }
534             }
535             catch ( IOException ex )
536             {
537                 getLog().warn( "Failed to close writer: " + ex.getMessage() );
538                 getLog().debug( ex );
539             }
540         }
541 
542         return success;
543     }
544 }