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 1742353 2016-05-05 03:22:53Z schulte $
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                 xmlStreamReader.close();
412                 xmlStreamReader = null;
413             }
414             catch ( IOException e )
415             {
416                 throw new MavenReportException( "Exception during filtering changes file : " + e.getMessage(), e );
417             }
418             catch ( MavenFilteringException e )
419             {
420                 throw new MavenReportException( "Exception during filtering changes file : " + e.getMessage(), e );
421             }
422             finally
423             {
424                 IOUtil.close( xmlStreamReader );
425             }
426 
427         }
428         return new ChangesXML( changesXml, getLog() );
429     }
430 
431     /**
432      * Add the issue link template for the given issue management system, but only if it has not already been
433      * configured.
434      *
435      * @param system The issue management system
436      * @param issueLinkTemplate The issue link template to use
437      * @since 2.4
438      */
439     private void addIssueLinkTemplate( String system, String issueLinkTemplate )
440     {
441         if ( caseInsensitiveIssueLinkTemplatePerSystem == null )
442         {
443             caseInsensitiveIssueLinkTemplatePerSystem = new CaseInsensitiveMap();
444         }
445         if ( !caseInsensitiveIssueLinkTemplatePerSystem.containsKey( system ) )
446         {
447             caseInsensitiveIssueLinkTemplatePerSystem.put( system, issueLinkTemplate );
448         }
449     }
450 
451     private void copyStaticResources()
452         throws MavenReportException
453     {
454         final String pluginResourcesBase = "org/apache/maven/plugin/changes";
455         String resourceNames[] = { "images/add.gif", "images/fix.gif", "images/icon_help_sml.gif", "images/remove.gif",
456             "images/rss.png", "images/update.gif" };
457         try
458         {
459             getLog().debug( "Copying static resources." );
460             for ( String resourceName : resourceNames )
461             {
462                 URL url = this.getClass().getClassLoader().getResource( pluginResourcesBase + "/" + resourceName );
463                 FileUtils.copyURLToFile( url, new File( getReportOutputDirectory(), resourceName ) );
464             }
465         }
466         catch ( IOException e )
467         {
468             throw new MavenReportException( "Unable to copy static resources." );
469         }
470     }
471 
472     private ResourceBundle getBundle( Locale locale )
473     {
474         return ResourceBundle.getBundle( "changes-report", locale, this.getClass().getClassLoader() );
475     }
476 
477     protected String getTeamlist()
478     {
479         return teamlist;
480     }
481 
482     private void logIssueLinkTemplatePerSystem( Map<String, String> issueLinkTemplatePerSystem )
483     {
484         if ( getLog().isDebugEnabled() )
485         {
486             if ( issueLinkTemplatePerSystem == null )
487             {
488                 getLog().debug( "No issueLinkTemplatePerSystem configuration was found" );
489             }
490             else
491             {
492                 for ( Entry<String, String> entry : issueLinkTemplatePerSystem.entrySet() )
493                 {
494                     getLog().debug( "issueLinkTemplatePerSystem[" + entry.getKey() + "] = " + entry.getValue() );
495                 }
496             }
497         }
498     }
499 
500     private boolean generateFeed( final ChangesXML changesXml, final Locale locale )
501     {
502         getLog().debug( "Generating " + feedType + " feed." );
503 
504         boolean success = true;
505 
506         final FeedGenerator feed = new FeedGenerator( locale );
507         feed.setLink( project.getUrl() + "/changes-report.html" ); // TODO: better way?
508         feed.setTitle( project.getName() + ": " + changesXml.getTitle() );
509         feed.setAuthor( changesXml.getAuthor() );
510         feed.setDateFormat( new SimpleDateFormat( publishDateFormat, new Locale( publishDateLocale ) ) );
511 
512         Writer writer = null;
513 
514         try
515         {
516             writer = new FileWriter( new File( getReportOutputDirectory(), "changes.rss" ) );
517             feed.export( changesXml.getReleaseList(), feedType, writer );
518         }
519         catch ( IOException ex )
520         {
521             success = false;
522             getLog().warn( "Failed to create rss feed: " + ex.getMessage() );
523             getLog().debug( ex );
524         }
525         finally
526         {
527             try
528             {
529                 if ( writer != null )
530                 {
531                     writer.close();
532                 }
533             }
534             catch ( IOException ex )
535             {
536                 getLog().warn( "Failed to close writer: " + ex.getMessage() );
537                 getLog().debug( ex );
538             }
539         }
540 
541         return success;
542     }
543 }