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:

It could be tedious or impractical to specify all individual command line options for certain aspects of EMMA behavior (e.g., coverage report generation properties). A large set of EMMA property value overrides can be kept in a file that is referenced with a single option or from the classpath.
Certain kinds of instrumented runtimes cannot be configured easily via command line options (e.g., servlets or Enterprise Java Beans (EJBs)). Again, other ways of passing property overrides are need in such cases, such the JVM system options or classpath resource files.

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 emma.property;
as a property named emma.property 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.

Examples

The following shows different ways of overriding the default coverage session dump file pathname from ANT or command line. Using emma.properties 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="my.properties"
              classname="Main"
              classpathref="run.classpath"
    />

where file my.properties sets session.out.file to some mydir/myfile value.

From command line:

>java emmarun -Dsession.out.file=mydir/myfile ...
>java emmarun -properties my.properties ...
>java -cp {directory containing emma.properties} emmarun ...
>java -Demma.session.out.file=mydir/myfile emmarun ...
>java -Demma.properties=my.properties emmarun ...

where file my.properties 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):

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.
A property can be set in an external java.util.Properties file whose pathname is the value of the JVM system property emma.properties (-Demma.properties=filename). EMMA properties in such a file are not prefixed with “emma.”.
A property can be set at the JVM system property level, using -Demma.property=value syntax.
A property can be set in a classloader resource named emma.properties 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.
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.”.
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 report.name 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 report.report_type.name 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.


7.2. Common command line options		2. EMMA property summary