Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>Currently, the character encoding for reports output files needs to be configured individually for each and every plugin that creates new report types (i.e. don't write its content through Doxia but write directly its files to disk).</p>

<p>Life would become easier if there was a dedicated POM element like <code><strong>${project.reporting.outputEncoding}</strong></code> which could be used to specify the encoding once per entire project. Every plugin could use it as default value, like it has been done with <a class="confluence-link" href="/display/MAVENUSER/POM+Element+for+Source+File+Encoding" data-linked-resource-id="50659353" data-linked-resource-type="page" data-linked-resource-default-alias="POM Element for Source File Encoding" data-base-url="http://docs.codehaus.org">source files encoding</a>:</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
* @parameter expression="${outputEncoding}" default-value="${project.reporting.outputEncoding}"
*/
private String outputEncoding;
</pre></td></tr></table>
<p>Adding this element to the POM structure without breaking backward compatibility can only happen in a future version, yet to be defined (at least after Maven 3.0):</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;project>
  ...
  &lt;reporting>
    &lt;outputEncoding>UTF-8&lt;/outputEncoding>
    ...
  &lt;/reporting>
  ...
&lt;/project>
</pre></td></tr></table>
<p>For  Maven 2.x, the value can be defined as an equivalent property:
<br class="atl-forced-newline" /></p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;project>
  ...
  &lt;properties>
    &lt;project.reporting.outputEncoding>UTF-8&lt;/project.reporting.outputEncoding>
    ...
  &lt;/properties>
  ...
&lt;/project>
</pre></td></tr></table>
<p>Thus plugins could immediately be modified to use <code>${project.reporting.outputEncoding</code>} expression, whatever Maven version is used.</p>

<h2>Default Value</h2>

<p>Actually, default output encoding vary between plugins:</p>
<ul>
	<li>ISO-8859-1 for maven-site-plugin, maven-jxr-plugin and by extension every reporting plugin generating content with maven-site-plugin's template (that is the vast majority of reporting plugins),</li>
	<li>UTF-8 for cobertura-maven-plugin,</li>
	<li>platform encoding for maven-javadoc-plugin.
<br class="atl-forced-newline" /></li>
</ul>

<p>Unifying default value will lead to a change for plugins previously using another default value. This shouldn't cause much harm since reports are mainly read by humans through their web browser.</p>

<p>After a <a href="http://www.nabble.com/-POLL--Default-Value-for-Reports-Output-Encoding-td18838502.html">poll on user list</a>, the default value is <strong>UTF-8</strong>, which will ensure that default value is appropriate for characters in any language in the world.</p>

<p>A check has to be coded in every plugin with the default value:</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
/**
* Gets the effective reporting output files encoding.
*
* @return The effective reporting output file encoding, never &lt;code>null&lt;/code>.
*/
protected String getOutputEncoding()
{
    return ( outputEncoding != null ) ? outputEncoding : ReaderFactory.UTF_8;
}
</pre></td></tr></table>
<p>This default value can be coded in POM model too when available (default value of the outputEncoding attribute) and in super-pom in Maven 2.x. But this change is only for clarity since without it, the previous check coded in every plugin will transform <em>null</em> value to the chosen default value.</p>

<p>For the record, the other proposed unified default value was <strong>source encoding</strong> as defined in <a class="confluence-link" href="/display/MAVENUSER/POM+Element+for+Source+File+Encoding" data-linked-resource-id="50659353" data-linked-resource-type="page" data-linked-resource-default-alias="POM Element for Source File Encoding" data-base-url="http://docs.codehaus.org">Source File Encoding</a> proposal, which would vary from project to project. Since users are invited to set a fixed value for source encoding in their poms to ensure build reproducibility, such calculated value wouldn't affect build reproducibility, but wouldn't have been appropriate in every case (for example, if project's description in pom.xml contains characters that can't be output with source files encoding).</p>

<h2>Plugins to Modify</h2>

<p>The vast majority of reporting plugins don't need any change since they are using Doxia and maven-site-plugin's template: the encoding configuration will silently be inherited from maven-site-plugin. </p>

<p><strong>Affected Apache plugins:</strong></p>
<ul class="alternate">
	<li>maven-changelog-plugin</li>
	<li>maven-javadoc-plugin: <a href="http://jira.codehaus.org/browse/MJAVADOC-206">MJAVADOC-206</a>, done in 2.5</li>
	<li>maven-jxr-plugin: <a href="http://jira.codehaus.org/browse/JXR-67">JXR-67</a>, done in 2.2-SNAPSHOT</li>
	<li>maven-pmd-plugin: <a href="http://jira.codehaus.org/browse/MPMD-83">MPMD-83</a></li>
	<li>maven-site-plugin: <a href="http://jira.codehaus.org/browse/MSITE-340">MSITE-340</a>, done in 2.0</li>
</ul>

<p><strong>Affected Codehaus plugins:</strong></p>
<ul>
	<li>cobertura-maven-plugin</li>
</ul>

<h2>References</h2>

<p>Please see [0] for the related thread from the mailing list and [1] for the corresponding feature request in JIRA.</p>

<p>[0] <a href="http://www.nabble.com/next-step-for-encoding-support%3A-reporting-output-files-td17580091.html">next step for encoding support: reporting output files</a></p>