Special Character Encoding Properties


November 19, 2009 By Anders Hammar

The other week I listened to Dennis Lundberg’s presentation “Site creation with Maven” and learned something new. As most of us living outside the plain ASCII world have experienced, character encoding makes a big difference when it comes to ensuring that text remains readable. For XML files, the encoding can be defined through the XML header which makes it possible for an XML file reader to decide on the proper encoding. But for other types of files such as Java source files and properties files, the encoding has to be defined outside of the actual source file.

Even though encoding seems to be handled correctly in your environment, with your local language settings or some implicit default value, the best practice is to always explicitly define the character encoding. This will make sure that your build is portable and it will also protect you in the future in case some of your default values change. The bottom line is, just do it!

In the Maven world, you need to specify the character encoding for every plugin that processes source files or creates reports. It would have been great if this were made possible through a shared configuration element in the POM, but that would require an update to the POM model and that won’t happen until Maven 3.x. In the meantime, two special properties have been defined.

project.build.sourceEncoding

project.reporting.outputEncoding

If these properties are set, most plugins will use the character encoding defined through them. So now we don’t have to individually configure all plugins. If needed, the encoding defined through the properties can be overridden by defining some other encoding in the plugin’s configuration. As always, some plugin could work differently and you should always consult the plugin’s documentation.

More information about the thoughts behind these special properties and how to use them can be found in the proposals below. On these pages you can also find out which plugins have been updated to use these properties.

Dennis, thanks for the tip!