Chapter 3. EMMA Property Reference

Table of Contents

1. Specifying EMMA properties
2. EMMA property summary

The behavior of EMMA tools and runtime is influenced by a number of EMMA properties (see Section 2, “EMMA property summary” for the full list). These properties address several needs:

1. Specifying EMMA properties

Given an EMMA property (from the tables in Section 2, “EMMA property summary”), it can be specified in several different ways:

  • as a JVM system property named;
  • as a property named defined in an external java.util.Properties file;
  • as a property named property defined in a java.util.Properties classloader resource;
  • as an explicit ANT task <property> or command line (-D) property override.
The general rule is that when a property is provided at the JVM system level, its name must be prefixed with “emma.” in order to be in EMMA namespace.


The following shows different ways of overriding the default coverage session dump file pathname from ANT or command line. Using or properties ANT is convenient when you want to load a large block of EMMA property settings without keeping them in your makefile or build.xml:

  • From ANT:

        <emmajava enabled="${emma.enabled}" libclasspathref="emma.lib" 
                  dumpsessiondata="yes" properties=""
    where file sets session.out.file to some mydir/myfile value.

  • From command line:

    >java emmarun -Dsession.out.file=mydir/myfile ...
    >java emmarun -properties ...
    >java -cp {directory containing} emmarun ...
    >java -Demma.session.out.file=mydir/myfile emmarun ...
    >java emmarun ...
    where file sets session.out.file to some mydir/myfile value.

EMMA property lookup order. Because of multiple ways to specify the same EMMA property, it is necessary to document the exact property lookup mechanism in order to disambiguate potential conflicts. The following lists all possible property lookup layers, in the order from the least specific to the most specific (in other words, later definitions override earlier definitions):

  1. Certain properties like report.txt.out.encoding, start out with their default values reflecting Java built-in system properties like file.encoding. Other properties have their defaults set in EMMA code.
  2. A property can be set in an external java.util.Properties file whose pathname is the value of the JVM system property ( EMMA properties in such a file are not prefixed with “emma.”.
  3. A property can be set at the JVM system property level, using syntax.
  4. A property can be set in a classloader resource named using the usual java.util.Properties format (without the “emma.” prefix). The resource is looked up first in the most specific of the {current, thread context} pair of classloaders. If neither one is more specific, the lookup is done in the current classloader. If the system classloader is more specific than either the current or the context classloader, then the system classloader is used.
  5. A property can be set in an external java.util.Properties file whose pathname is the value of a properties ANT task attribute or a -properties command line option. EMMA properties in such a file are not prefixed with “emma.”.
  6. A property can be set via a property ANT task nested element (<property name='name' value='value'/>) or a -D EMMA command line option (-Dproperty=value). (Without the “emma.” prefix: don't confuse this with JVM system properties.) Note that in the <report> task case this mechanism is largely redundant, because all report generation properties have dedicated ANT task attributes.

Property shortcuts. In the special case of report generation properties (report.*) there is one additional complication. Any property name that follows the patterns is actually a report property shortcut in the sense that is applies to all report types (plain text, HTML, XML). For some aspects of report generation (e.g., report.units) this is very appropriate, but for others (e.g., report.out.encoding) you are likely to want report type-specific settings. To do so, you can specify a property. For example, report.txt.out.encoding is more specific than report.out.encoding as far as the plain-text report generator is concerned. Note that the <report> ANT task makes this more convenient that the command line case, because it provides convenience override attributes on all nested <txt>, <html>, etc elements.