Default JDK file encoding and Eclipse, running on Mac OS X

File encoding is notoriously a difficult problem for developers to fully grok. Development environments and IDEs do not always help.

I recently had a test failing under Eclipse, whereas the same test was passing fine in the command line using Maven. Here are some details on the context, and a workaround.

It turns out that JDK 1.6 (provided by Apple) is configured by default with the MacRoman charset, a rather obsolete choice. Meaning that the Java compiler assumes that .java files are encoded in this character set. This is usually not a problem as most Java is using plain ASCII characters. However, in my case, there was a JUnit test written with extended UTF-8 character.

Interestingly, that was not a problem when compiling in the command line with Maven. It turns out that a parent POM had already set the encoding to UTF-8.

However, running the test under an IDE was an entirely different story:

• Eclipse uses the default platform encoding (MacRoman), and fails the test; the mvn eclipse:eclipse command did not propagate the encoding to the Eclipse configuration files
• NetBeans also uses the default platform encoding; I expected it to pick up the encoding from the pom.xml (use as the project configuration), but that didn’t help; the test failed
• IntelliJ, however, enforces the encoding to UTF-8, regardless of the JDK configuration; the test passed

To enforce the encoding on Eclipse, one obvious option is to change the “Text file encoding” option in Preferences > General > Workspace. However, that must be done for each installation of Eclipse.

My preferred solution is to request mvn eclipse:eclipse to update Eclipse properties:

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-eclipse-plugin</artifactId>
        <version>2.6</version>
        <configuration>
          <additionalConfig>
            <file>
              <name>.settings/org.eclipse.core.resources.prefs</name>
              <content>
                <![CDATA[eclipse.preferences.version=1${line.separator}encoding/<project>=${project.build.sourceEncoding}${line.separator}]]>
              </content>
            </file>
          </additionalConfig>
        </configuration>
      </plugin>
    </plugins>
  </build>

This will create a org.eclipse.core.resources.prefs file under .settings every time mvn eclipse:eclipse is run. If you already have an existing org.eclipse.core.resources.prefs file, then you might need to replace the <content> clause with a <file> clause.

Last point: you might think that this will get fixed in later versions of the JDK. Well, the JDK 1.7 as provided by Oracle does not set the encoding to MacRoman anymore, but to… US-ASCII. Unlikely to solve my problem.