docs.data.docbook.reference.xml Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of emma_ant Show documentation
Show all versions of emma_ant Show documentation
EMMA is a fast Java code coverage tool based on bytecode instrumentation. It differs from the existing tools by enabling coverage profiling on large scale enterprise software projects with simultaneous emphasis on fast individual development.
The newest version!
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY PROD "EMMA">
<!ENTITY prod "emma">
<!ENTITY DIAGNOSTICS
"<simpara>The default &PROD; command line tool behavior is not to use
<function>System.exit()</function> on exit unless an explicit
<link linkend='commonoptions.cmdline.exit'><option>-exit</option></link>
option is specified. If that is done, the error codes returned via
<function>System.exit()</function> are as follows:</simpara>
<informaltable frame='none' pgwide='1'>
<tgroup cols='2'>
<colspec align='right' colwidth='0.5in' />
<colspec align='left' />
<tbody>
<row>
<entry valign='top'><constant>0</constant></entry>
<entry>Successful completion.</entry>
</row>
<row>
<entry valign='top'><constant>1</constant></entry>
<entry>Failure due to incorrect option usage. This error
code is also returned when command line usage
(<link linkend='commonoptions.cmdline.h'><option>-h</option></link>)
is requested explicitly.</entry>
</row>
<row>
<entry valign='top'><constant>2</constant></entry>
<entry>All other failures.</entry>
</row>
</tbody>
</tgroup>
</informaltable>"
>
<!ENTITY TGROUP_ANT3
"<colspec colname='c1' colwidth='2*'/>
<colspec colname='c2' colwidth='3*'/>
<colspec colname='c3' colwidth='1*' align='center'/>"
>
<!ENTITY PROPREF_FO
"<?dbhtml list-presentation='table' ?>
<?dbfo list-presentation='list' ?>"
>
<!ENTITY RUN "<command><∏java></command>/<command>∏run</command>">
<!ENTITY INSTR "<command><instr></command>/<command>instr</command>">
<!ENTITY REPORT "<command><report></command>/<command>report</command>">
<!ENTITY MERGE "<command><merge></command>/<command>merge</command>">
<!ENTITY ALLCLASSES "<constant>all classes</constant>">
]>
<?PSGML NOFILL programlisting screen?>
<book id="start">
<!-- TODO: make usage consistent: offline coverage mode vs offline -->
<!-- instrumentation mode vs offline processing mode -->
<bookinfo>
<title>&PROD; Reference Manual</title>
<copyright>
<year>2001-2006</year>
<holder>Vlad Roubtsov</holder>
</copyright>
</bookinfo>
<!-- ================================================================= -->
<chapter>
<title>Installation and System Requirements</title>
<formalpara>
<title>Supported JRE versions.</title>
<para>&PROD; has been implemented to work in any J2SE runtime
environment. For performance reasons, &PROD; tools and runtime can
benefit from (but do not require) J2SE APIs available in J2SE versions 1.3
and 1.4. &PROD; command line tools, ANT tasks, and runtime have been
tested in a variety of JREs from Sun Microsystem, IBM, and BEA.</para>
</formalpara>
<formalpara>
<title>Supported ANT versions.</title>
<para>&PROD; ANT tasks work with Apache ANT 1.4.1 and later
versions.</para>
</formalpara>
<formalpara>
<title>External library dependencies.</title>
<para>&PROD; has no external Java or native library dependencies.</para>
</formalpara>
<formalpara>
<title>Operating system.</title>
<para>&PROD; is a pure Java application and does not use JVMPI or other
profiling interfaces requiring native libraries. It should provide identical
functionality on any operating system supported by J2SE
v1.2+<footnote><para>In a Sun Microsystems-compatible JRE prior to version
1.3 the runtime coverage data is dumped (in the offline coverage mode) only when
the JVM is terminated via <option>Ctrl-C</option> or an equivalent
signal.</para></footnote>.</para>
</formalpara>
<formalpara><title>&PROD; distribution.</title>
<para>&PROD; is contained in two Java class archives (found in the
<filename>lib</filename> subdirectory of &PROD; distribution):
<variablelist>
<varlistentry><term><filename>∏.jar</filename></term>
<listitem>
<simpara>Contains the implementation of &PROD; core components
command line tools, and <emphasis>&PROD; runtime classes</emphasis>
(&PROD; classes that are needed by Java application code that has been
instrumented for coverage).</simpara>
</listitem>
</varlistentry>
<varlistentry><term><filename>∏_ant.jar</filename></term>
<listitem>
<simpara>Contains the implementation of &PROD; ANT tasks (this
archive depends on <filename>∏.jar</filename> and does not
overlap with it in content).</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</formalpara>
<formalpara><title>General installation considerations.</title>
<para>"Installing" &PROD; simply implies making
<filename>∏.jar</filename> and <filename>∏_ant.jar</filename>
available to the Java Runtime Environment (<acronym>JRE</acronym>) and
Apache ANT runtime, as appropriate.</para>
</formalpara>
<para>There are two distinct runtime cases for &PROD;:
<orderedlist numeration='loweralpha'>
<listitem>
<simpara>Execution of an &PROD; command line tool or ANT task.</simpara>
</listitem>
<listitem>
<simpara>Execution of some Java code that has been instrumented for
coverage. Note that every &PROD;-instrumented class becomes dependent on
&PROD; runtime classes (contained in <filename>∏.jar</filename>).</simpara>
</listitem>
</orderedlist>
</para>
<formalpara id='install.core'><title>Installing &PROD; core/runtime library.</title>
<para>Accordingly, to run &PROD; command line tools or &PROD;-instrumented
applications you need to add
<filename>∏.jar</filename> to the appropriate JRE classpath. You
can do it either via the <option>-cp</option> JVM option or by adding
<filename>∏.jar</filename> as an <emphasis>installed JRE extension</emphasis> (by copying
<filename>∏.jar</filename> to <filename>lib/ext</filename>
subdirectory of your JRE or by setting the
<option>java.ext.dirs</option> JVM system property to include the
<filename>lib</filename> subdirectory of &PROD; distribution. See
Sun's documentation on <ulink
url="http://java.sun.com/docs/books/tutorial/ext/basics/install.html">Installed
Extentions</ulink> and <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/extensions/spec.html#installed"><option>java.ext.dirs</option></ulink>
property for more details).
<important id='install.note.jreext'><title>The JRE extension option is preferred</title>
<para>It is <emphasis>highly recommended</emphasis> to install
<filename>∏.jar</filename> as a JRE extension. This simplifies
&PROD; usage with application containers (IBM Websphere, BEA
WebLogic, etc). Furthemore, installed JRE extensions are
<emphasis>trusted</emphasis> by default: the instrumented
application classes will automatically have the necessary
runtime permissions for dumping coverage data files. Note that the JRE used by
an application container may not necessarily be the same one you use
from command line or ANT.</para>
</important>
</para>
</formalpara>
<formalpara id='install.ANT'><title>Setting up &PROD; ANT tasks.</title>
<para>To run &PROD; ANT tasks, one additional configuration step inside
<filename>build.xml</filename> is required:</para>
</formalpara>
<!-- TODO: verify -->
<programlisting><![CDATA[
<!-- ]]>&PROD;<![CDATA[ distribution directory: -->
<property name=']]>∏<![CDATA[.dir' value=']]><emphasis>your &PROD; install location</emphasis><![CDATA[' />
<path id=']]>∏<![CDATA[.lib' >
<fileset dir='${]]>∏<![CDATA[.dir}' includes='lib/*.jar' />
</path>
<taskdef resource=']]>∏<![CDATA[_ant.properties' classpathref=']]>∏<![CDATA[.lib' />]]></programlisting>
<para>
<note><title>&PROD; lib path</title>
<para>The <filename>build.xml</filename> snippet shown above defines a
path element with <option>∏.lib</option> <!-- TODO: cite the ANT
Reference page -->reference id. Although
this is not strictly necessary (the <option><classpath></option>
element nested inside the <option><taskdef></option> could have worked
just as well), such a path element usually comes in handy elsewhere in
the <filename>build.xml</filename>.</para>
</note>
</para>
<!-- TODO: detail what happens when ∏.jar is in the instr path + mention ANT clsld problems -->
</chapter>
<!-- ================================================================= -->
<chapter>
<title>&PROD; Tool Reference</title>
<!-- =================== OVERVIEW ====================== -->
<sect1 id='tool-ref.overview'><title>Overview</title>
<para>&PROD; functionality is implemented by a set of components
responsible for class instrumentation, metadata and coverage data
processing, and coverage report generation. Each component has
adapters that expose its functionality as an ANT task and a
command line tool. To reflect this design, each of the following
reference subsections starts by detailing the overall functionality
of a given component, followed by its concrete ANT and command line
usage.</para>
<para>The following table summarizes &PROD; ANT tasks and their equivalent
command line tools:</para>
<para>
<table frame='all' tocentry='1'><title>&PROD; ANT tasks and command line tools</title>
<tgroup cols='4' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth='2*'/>
<colspec colname='c2' colwidth='2*'/>
<colspec colname='c3' colwidth='3*'/>
<colspec colname='c4' colwidth='3*'/>
<thead>
<row>
<entry>ANT task</entry>
<entry>Command line tool</entry>
<entry>Functionality</entry>
<entry>Output</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c4" align="center"><emphasis>on-the-fly
processing mode</emphasis></entry>
</row>
<row>
<entry><link linkend='tool-ref.run.ANT'><command><∏java></command></link></entry>
<entry><link linkend='tool-ref.run.cmdline'><command>∏run</command></link></entry>
<entry>Executes a standalone Java application in &PROD;
instrumenting classloader without a separate instrumentation phase.</entry>
<entry>One or several coverage reports and (optionally) a coverage
session raw data file.</entry>
</row>
<row>
<entry namest="c1" nameend="c4" align="center"><emphasis>offline
processing mode</emphasis></entry>
</row>
<row>
<entry><link
linkend='tool-ref.instr.ANT'><command><instr></command></link> subtask</entry>
<entry><link
linkend='tool-ref.instr.cmdline'><command>instr</command></link> command</entry>
<entry>Instruments a set of classes in a given list of
directories and/or archives and output.</entry>
<entry>Instrumented classes and archives and a coverage metadata file.</entry>
</row>
<row>
<entry><link linkend='tool-ref.report.ANT'><command><report></command></link> subtask</entry>
<entry><link linkend='tool-ref.report.cmdline'><command>report</command></link> command</entry>
<entry>Combines class metadata and coverage runtime data to
produce coverage reports.</entry>
<entry>One or several coverage reports (plain text, HTML, XML).</entry>
</row>
<row>
<entry><link linkend='tool-ref.merge.ANT'><command><merge></command></link> subtask</entry>
<entry><link linkend='tool-ref.merge.cmdline'><command>merge</command></link> command</entry>
<entry>Merges and compacts several metadata, coverage, or
session data files.</entry>
<entry>A single merged coverage session data file.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<formalpara>
<title>Subtasks and commands.</title>
<para>For reasons that include modularity and consistency of
common option behavior &PROD; offline coverage tools are used as
subtasks of the "umbrella" <command><∏></command> ANT
task:</para>
</formalpara>
<programlisting>
<![CDATA[
<]]>∏<![CDATA[ ...>
<merge ...>
...
</merge>
<report ...>
...
</report>
</]]>∏<![CDATA[>]]>
</programlisting>
<simpara>or as subcommands of the "umbrella" <command>∏</command>
command line command:</simpara>
<screen><![CDATA[
>java ]]>∏<![CDATA[ instr -ip out/classes/ ...
>java ]]>∏<![CDATA[ report -in coverage.em,coverage.ec ...]]></screen>
<simpara>Note that in the ANT case, <command><∏></command> can
contain an arbitrary sequence of subtasks (including mutliple subtasks of the
same kind, which are executed in the exact sequence as they are
specified). In addition to the already mentioned advantages, this allows
entire blocks of &PROD; tool invocations to be enabled/disabled and
configured using attributes of the parent <command><∏></command> ANT task.</simpara>
<formalpara>
<title>&PROD; properties cascade.</title>
<para>Some aspects of &PROD; tool/task behavior can be modified
using properties which can be set in a variety of ways: via
JVM system properties, via an external file, via ANT (sub)task
attributes or command line tool options. The task-subtask
organization helps with this &PROD; configuration as well. The
general rule of thumb here is that properties within a more specific
context (an ANT subtask vs <command><∏></command> parent task, a tool
setting vs a global JVM property, etc) inherit their values from the
surrounding contexts, but can also override them. For complete details see
<xref linkend='prop-ref.lookup'/></para>
</formalpara>
<simpara>In the remainder of this manual, the same tool will be
frequently referred to as
<command><<replaceable>ANT_tool_name</replaceable>></command>/<command><replaceable>command_line_tool_name</replaceable></command>.</simpara>
<formalpara>
<title>Overall &PROD; processing sequence.</title>
<para>The general sequence of steps when using &PROD; depends on your
chosen coverage mode:
<itemizedlist>
<listitem>
<para>When using &PROD;'s on-the-fly coverage mode, there is little to do
in addition to how you would normally run your application or
testsuite: you use
<command><∏java></command>/<command>∏run</command> as the new startup
class and optionally tell it where to place the coverage
report(s)<footnote><para>Usually, <command><∏java></command>
(<command>∏run</command>) runs correspond to
completely independent application/testsuite runs. However, its
<option>-raw</option> option could be used to retain coverage
session data files across different runs, to be processed later
by tools like &REPORT; and &MERGE;.</para></footnote>.</para>
</listitem>
<listitem>
<para>When using &PROD;'s offline coverage mode, the general sequence of
tool/task invocations is:
<orderedlist>
<listitem>
<para>In one or several passes, use
&INSTR;
to instrument class directories and archive files.</para>
</listitem>
<listitem>
<para>Execute your application or test suite using the
instrumented classes (one or several runs).</para>
</listitem>
<listitem>
<para>Optionally, merge and compact all <glossterm linkend='mdata'>metadata</glossterm> and
<glossterm linkend='rdata'>runtime coverage</glossterm> files using &MERGE;.</para>
</listitem>
<listitem>
<para>In one or several passes, use
&REPORT; to combine class metadata
with the desired runtime coverage
data profile(s) and generate the desired coverage report(s).</para>
</listitem>
</orderedlist>
</para>
</listitem>
</itemizedlist>
</para>
</formalpara>
<formalpara><title>&PROD; data files are untyped.</title>
<para>&PROD; tools use binary data files for storing instrumentation
and runtime coverage results. &PROD; files are not typed: they do not
require a particular name or extension. Furthermore, each data file is
a mini-database that acts as an envelope for an arbitrary sequence of
metadata and/or runtime coverage data dumps. It is up to the user how to
structure their work with &PROD;: either accumulate everything in a
single file or use a dedicated file for every tool. The
only restriction is that &PROD; files can only grow (once new data is
merged in, it cannot be removed).</para>
</formalpara>
</sect1>
<!-- =================== RUN ====================== -->
<sect1 id='tool-ref.run'><title>&RUN;</title>
<para>&RUN; — instrumented application runner (on-the-fly
instrumentation mode).</para>
<sect2><title>Description</title>
<para>&RUN; pairs an advanced custom classloader with a
combination of core internal components of &INSTR; and
&REPORT; to form a unique convenience tool in &PROD; kit: an application
runner that instruments classes <emphasis>on the fly</emphasis> and generates coverage
reports without any need for a separate build or any intermediate
work files alltogether.</para>
<para>&RUN; convenience is especially apparent in command line mode,
because its option names intentionally mimick the familiar
<command>java</command> options: a Java application launch command
line could be made coverage-enabled by inserting a single new word
(<command>∏run</command>)
into the command line. Similarly, the ANT version of this tool is an
extension of ANT's standard <java> task. &RUN; can execute as
little as a single Java class or as
much as a complex Swing application made up of hundreds of classes,
all with equally small instrumentation overhead.</para>
<para>Thinking of &RUN; as a combination of &PROD; class
instrumentor and report generator is a good way to remember its ANT
attributes and command line options: in the reference sections that
follow most of them are documented as identical to their namesakes
in <link linkend='tool-ref.instr'>&INSTR;</link> and <link
linkend='tool-ref.report'>&REPORT;</link>.</para>
<formalpara><title>What gets instrumented.</title>
<para>The default &RUN; behavior is to instrument only the classes
that are loaded by the JVM for the running application. The
resulting report will not even mention classes that were never
loaded and which potentially decrease your coverage
percentages. If your objective is to get a complete coverage
report (as you would from an offline combination of &INSTR; and
&REPORT;) you should use the <link
linkend="tool-ref.run.fullmetadata.ANT">option for a full classpath scan</link>,
possibly in combination with some <link linkend="instrset.filters">coverage filters</link>.</para>
</formalpara>
<formalpara><title>Compatibility.</title>
<para>At runtime, &RUN;'s instrumenting classloader installs
itself as the application classloader, bypassing the standard
system classloader. It uses a smart class
delegation strategy, whereby it automatically detects JRE core and
extension classes without having to filter by class names (the
frequently used, but inadequate, delegation strategy). Coupled
with full support for <option>Class-Path</option> manifest entries
and <option>-jar</option> option, the resulting &PROD; runtime will
correctly run most standalone Java programs. However, certain cases are
exceptions:
<itemizedlist>
<listitem>
<simpara>Java code referencing
<function>java.lang.ClassLoader.getSystemClassLoader()</function>
(either directly or via
<function>ClassLoader.findSystemClass()</function> and
related methods)
instead of using the current or thread context loaders will
bypass &RUN; classloader, causing subsequent classes to be
loaded at the wrong node of the classloader hierarchy. Such coding patterns should
really be considered bugs and are not supported. Such
code could be patched up on the fly during instrumentation,
but a reliable solution is expensive in terms of
processing. Switching to offline instrumentation is an easy
workaround.</simpara>
</listitem>
<listitem>
<simpara>Java applications designed around their own custom
classloaders and classpaths most likely will not work with &RUN; (at
best, they will run fine but coverage instrumention will not
occur). Application containers (Apache tomcat, BEA
Weblogic, IBM Websphere, etc) are the common case
here. Again, switching to offline instrumentation is an easy
alternative.</simpara>
</listitem>
</itemizedlist>
</para>
</formalpara>
<!-- TODO: describe session data dump + -raw option -->
<formalpara><title><command><∏java></command> is always forked.</title>
<para>ANT's in-process classloading model is not sufficiently
JRE-compatible. ANT's class
delegation in the standard <command><java></command> task in
<option>fork='false'</option> (in-process) mode is
based on name matching (with a hardcoded set of name
filters) and inevitably fails for applications that depend on
non-standard JRE extensions. To support &PROD; deployment as a JRE
extension <command><∏java></command> always forces
<option>fork='true'</option> to ensure correct execution (unless
its <option>enabled</option> attribute makes it a pass-through).</para>
</formalpara>
<formalpara><title>Internal &PROD; properties that affect classloading and class instrumentation.</title>
<para>Several &PROD; property settings affect instrumentation and
classloading behavior done by &RUN;:
<itemizedlist>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.do_suid_compensation'/></phrase></simpara>
</listitem>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.exclude_synthetic_methods'/></phrase></simpara>
</listitem>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.exclude_bridge_methods'/></phrase></simpara>
</listitem>
</itemizedlist>
</para>
</formalpara>
<simpara>Changing the default classloading behavior should be done by
experienced Java users only. Most of instrumentation-related
properties should normally be left with their default
values. <phrase role='property'><xref linkend='prop-ref.instr.do_suid_compensation'/></phrase>
can be set to <option>false</option> to gain extra instrumentation
processing speed when runtime execution does not involve class
de-serialization from existing files or serialization across
JVMs.</simpara>
<!-- TODO: need to explain the java -cp A ∏run -cp B scenario -->
</sect2>
<sect2 id='tool-ref.run.ANT'><title>ANT usage</title>
<simpara><command><∏java></command> task is an implicit combination of <link
linkend='tool-ref.instr.ANT'><command><instr></command></link>
and <link
linkend='tool-ref.report.ANT'><command><report></command></link>
tasks and most of its attributes and nested elements are the same as
for those two tasks combined.</simpara>
<bridgehead>Parameters specified as attributes</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c3"
align="center">[<option><ulink
url='http://ant.apache.org/manual/CoreTasks/java.html'>stock
ANT <java> task attributes</ulink></option>]</entry>
</row>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task attributes</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.libclasspath.ANT'>
<entry valign='top'><option>libclasspath</option></entry>
<entry>A <citetitle>path-like structure</citetitle>
containing &PROD; core
(<filename>∏.jar</filename>).</entry>
<entry>Yes, unless &PROD; is <link linkend='install.core'>installed as
the JRE extension</link></entry>
</row>
<row id='tool-ref.run.libclasspathref.ANT'>
<entry valign='top'><option>libclasspathref</option></entry>
<entry>Same as <option>libclasspath</option>, but given as a reference to a
path defined elsewhere.</entry>
<entry>Yes, unless &PROD; is <link linkend='install.core'>installed as
the JRE extension</link></entry>
</row>
<row id='tool-ref.run.fullmetadata.ANT'>
<entry valign='top'><option>fullmetadata</option></entry>
<entry>Indicates whether the entire classpath should be
added to the coverage metadata (default: <option>false</option>).</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.dumpsession.ANT'>
<entry valign='top'><option>dumpsessiondata</option></entry>
<entry>Indicates whether the session (metadata+coverage)
data resulting from this coverage run should be dumped to
a file. Useful for post-run coverage report generation (default: <option>false</option>).</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.sessiondatafile.ANT'>
<entry valign='top'><option>sessiondatafile</option>, <option>outfile</option></entry>
<entry>If <option>dumpsessiondata='true'</option>, overrides the location to store session data
(default: file <filename>coverage.es</filename> in the current
directory). Ignored otherwise.
</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.merge.ANT'>
<entry valign='top'><option>merge</option></entry>
<entry>Indicates whether the session data should be merged
into the destination <option>sessiondatafile</option>, if
any (default: <option>true</option>). Any existing data is
clobbered otherwise.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.filter.ANT'>
<entry valign='top'><option>filter</option></entry>
<entry>Adds a coverage filter. See <xref linkend='instrset.filters'/> for
general description
of &PROD; coverage filters and <xref linkend='filtersyntax.ANT'/>
specifically for ANT syntax. This attribute plays a role
equivalent to <link linkend='tool-ref.instr.filter.ANT'>the same attribute</link>
of <link linkend='tool-ref.instr.ANT'><command><instr></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.sourcepath.ANT'>
<entry valign='top'><option>sourcepath</option></entry>
<entry>A <citetitle>path-like structure</citetitle> that can be used
to point the HTML report generator in &RUN; to the location of your Java
source files. It is interpreted as a list of
directories (separated by the OS-specific classpath
separator or comma) containing <filename>.java</filename>
source files. The local path names within each directory
should reflect class package names. This attribute is equivalent to the
<link linkend='tool-ref.report.sourcepath.ANT'>same attribute
of <link linkend='tool-ref.report.ANT'><command><report></command></link> task</link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.sourcepathref.ANT'>
<entry valign='top'><option>sourcepathref</option></entry>
<entry>Same as <option>sourcepath</option>, but given as a reference to a
path defined elsewhere.</entry>
<entry>No</entry>
</row>
<!-- TODO: make the order is the same as for nested configs -->
<row id='tool-ref.run.units.ANT'>
<entry valign='top'><option>units</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.units.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.depth.ANT'>
<entry valign='top'><option>depth</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.depth.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.columns.ANT'>
<entry valign='top'><option>columns</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.columns.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.sort.ANT'>
<entry valign='top'><option>sort</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.sort.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.metrics.ANT'>
<entry valign='top'><option>metrics</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.metrics.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.encoding.ANT'>
<entry valign='top'><option>encoding</option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.encoding.ANT'>the same attribute</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<bridgehead>Parameters specified as nested elements</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Element</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c3"
align="center">[<option><ulink
url='http://ant.apache.org/manual/CoreTasks/java.html'>stock
ANT <java> task nested elements</ulink></option>]</entry>
</row>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task nested elements</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.nested.filter.ANT'>
<entry valign='top'><option><filter></option></entry>
<entry>Adds a coverage filter. See <xref linkend='instrset.filters'/> for
general description of &PROD; coverage filters and <xref
linkend='filtersyntax.ANT'/> specifically for ANT
syntax. This nested element plays a role
equivalent to <link
linkend='tool-ref.instr.nested.filter.ANT'>the same
element</link> of <link linkend='tool-ref.instr.ANT'><command><instr></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.nested.sourcepath.ANT'>
<entry valign='top'><option><sourcepath></option></entry>
<entry>A <citetitle>path-like structure</citetitle> that can be used to point the HTML
report generator in &RUN; to the location of your Java source
files. This element is equivalent to the <link linkend='tool-ref.report.nested.sourcepath.ANT'>same nested element
of <link linkend='tool-ref.report.ANT'><command><report></command></link> task</link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.nested.txt.ANT'>
<entry valign='top'><option><txt></option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.nested.txt.ANT'>the same nested element</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.run.nested.html.ANT'>
<entry valign='top'><option><html></option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.nested.html.ANT'>the same nested element</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No (<option><txt></option> implied by default)</entry>
</row>
<row id='tool-ref.run.nested.xml.ANT'>
<entry valign='top'><option><xml></option></entry>
<entry>Equivalent to <link
linkend='tool-ref.report.nested.xml.ANT'>the same nested element</link>
of <link linkend='tool-ref.report.ANT'><command><report></command></link>.</entry>
<entry>No (<option><txt></option> implied by default)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<formalpara><title><option><txt></option>,
<option><html></option>, and <option><xml></option> nested elements.</title>
<para>These nested elements create plain text, HTML, and XML
coverage reports, respectively. If none is specified, the plain
text report is implied (at most one configurator of any given report type
can be nested inside a given
<command><∏java></command> call). Configuration of these
elements is described in the <link
linkend='report.nestedcfg'>equivalent section of <command><report></command>
task</link> reference page.</para>
</formalpara>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Generate plain text and HTML reports with the default parameters:
<programlisting><![CDATA[
<emmajava enabled="${emma.enabled}" libclasspathref="emma.lib"
filter="${emma.filter}" sourcepath="${src.dir}"
classname="Main" classpathref="run.classpath"
>
<!-- since this task is an extension of stock <java>, normal <java>
options are still available: -->
<arg value="someargvalue" />
<txt outfile="${coverage.dir}/coverage.txt" />
<html outfile="${coverage.dir}/coverage.html" />
</emmajava>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Do a full metadata scan (of <constant>run.classpath</constant>), generate
an HTML report with some customization, use a <command><dirset></command>
to set the sourcepath:
<programlisting><![CDATA[
<emmajava enabled="${emma.enabled}" libclasspathref="emma.lib"
fullmetadata="yes"
classname="Main" classpathref="run.classpath"
>
<sourcepath>
<dirset dir="${basedir}" >
<include name="**/src" />
</dirset>
</sourcepath>
<html outfile="${coverage.dir}/index.html"
columns="name, method, line"
sort="+line, +name"
metrics="line:80"
/>
</emmajava>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Don't generate any reports, just dump the raw coverage session data
for now:
<programlisting><![CDATA[
<emmajava enabled="${emma.enabled}" libclasspathref="emma.lib"
fullmetadata="yes" dumpsessiondata="yes"
classname="Main"
classpathref="run.classpath"
/>]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='tool-ref.run.cmdline'><title>Command line usage</title>
<bridgehead>Synopsis</bridgehead>
<cmdsynopsis>
<command>java ∏run</command>
<arg choice='opt'><synopfragmentref linkend='tool-ref.run.restofopts'>&PROD; options</synopfragmentref></arg>
<arg choice='plain' rep='repeat'>-cp <replaceable>classpath</replaceable></arg>
<arg choice='plain'><replaceable>class</replaceable></arg>
<arg choice='opt' rep='repeat'><replaceable>args</replaceable></arg>
<sbr/>
<command>java ∏run</command>
<arg choice='opt'><synopfragmentref linkend='tool-ref.run.restofopts'>&PROD; options</synopfragmentref></arg>
<arg choice='plain'>-jar <replaceable>jarfile</replaceable></arg>
<arg choice='opt' rep='repeat'><replaceable>args</replaceable></arg>
<sbr/>
<sbr/>
<!-- TODO: best opt presentation order -->
<synopfragment id='tool-ref.run.restofopts'>
<arg choice='opt'>-f</arg>
<arg choice='opt' rep='repeat'>-ix <replaceable>filter patterns</replaceable></arg>
<arg choice='opt' rep='repeat'>-r <replaceable>report types</replaceable></arg>
<arg choice='opt' rep='repeat'>-sp <replaceable>sourcepath</replaceable></arg>
<arg choice='opt'>-raw</arg>
<arg choice='opt'>-out <replaceable>session data file</replaceable></arg>
<arg choice='opt'>-merge <replaceable>boolean</replaceable></arg>
<arg choice='opt'><option><link linkend='commonoptions.cmdline'>common options</link></option></arg>
</synopfragment>
</cmdsynopsis>
<simpara>alternative form:</simpara>
<cmdsynopsis>
<command>java ∏ run</command>
<arg choice='req' rep='repeat'><replaceable>same as above</replaceable></arg>
</cmdsynopsis>
<bridgehead>Options</bridgehead>
<simpara>[<option><link linkend='commonoptions.cmdline'>common command line options</link></option>]</simpara>
<variablelist>
<varlistentry id='tool-ref.run.f.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-f, -fullmetadata</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This flag indicates whether the entire classpath
(<option>-cp</option>) should be added to the coverage
metadata (default: <option>false</option>). Without this flag,
only the classes explicitly loaded by the JVM will be in the
instrumentation set.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.ix.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-ix, -filter <replaceable>filter patterns</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option adds a coverage filter. See <xref linkend='instrset.filters'/> for
general description
of &PROD; coverage filters and <xref linkend='filtersyntax.cmdline'/>
specifically for command line syntax. It is equivalent to <link linkend='tool-ref.instr.ix.cmdline'>the same option</link>
of <link linkend='tool-ref.instr.cmdline'><command>instr</command></link>
tool.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.r.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-r, -report (<constant>txt</constant>|<constant>html</constant>|<constant>xml</constant>)</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option selects the
type of coverage report(s) to generate
(default: <option>txt</option>). It is equivalent to <link linkend='tool-ref.report.r.cmdline'>the same option</link>
of <link
linkend='tool-ref.report.cmdline'><command>report</command></link>
tool.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.sp.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-sp, -sourcepath <replaceable>list of source directories</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option can be used to point the HTML
report generator in &RUN; to the location of your Java source
files. Equivalent to <link
linkend='tool-ref.report.sp.cmdline'>the same option</link>
of <link
linkend='tool-ref.report.cmdline'><command>report</command></link>
tool.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.raw.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-raw, -sessiondata</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This flag indicates whether the session (metadata+coverage)
data resulting from this coverage run should be dumped to
a file. Useful for post-run coverage report generation (default: <option>false</option>).</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.out.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-out, -outfile <replaceable>session data file</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>If <option>-raw</option> flag is set, this option
overrides the location to store session data
(default: file <filename>coverage.es</filename> in the current
directory). Ignored otherwise.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.run.merge.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-merge (<constant>y[es]</constant>|<constant>n[o]</constant>)</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>Indicates whether the session data should be merged
into the destination <option>outfile</option>, if
any (default: <option>true</option>). Any existing data is
clobbered otherwise.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>report generation options</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>Unlike its ANT equivalent,
<command>∏run</command> command line tool does not have
dedicated options for controlling coverage report generation. If necessary, they can be
set using generic <link
linkend='commonoptions.property.cmdline'>-D</link>, <link
linkend='commonoptions.properties.cmdline'>-properties</link>,
and other mechanisms.</simpara>
<para>So, for example, to change the default location of
the HTML report you would override the <phrase role='property'><xref
linkend='prop-ref.report.out.file'/></phrase> property:
<screen><![CDATA[
>java emmarun -Dreport.html.out.file=mycoveragedir/myfile.html ...]]></screen>
(<option>report.html.out.file</option> can be abbreviated to
<option>report.out.file</option> if the command generates
a single report type)</para>
</listitem>
</varlistentry>
</variablelist>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Run an application and generate plain text and XML reports
with default parameters:
<screen><![CDATA[
>java emmarun -r txt,xml -jar SwingSet2.jar
]]></screen>
</para>
</listitem>
<listitem>
<para>Run an application and generate an HTML report with some customization
and linking to the application source code:
<screen><![CDATA[
>java emmarun -r html -Dreport.columns=name,method,line -sp src/ -jar SwingSet2.jar
]]></screen>
</para>
</listitem>
<listitem>
<para>Run an application and don't generate any reports, just dump the raw
coverage session data:
<screen><![CDATA[
>java emmarun -raw -jar SwingSet2.jar
]]></screen>
</para>
</listitem>
</itemizedlist>
<bridgehead>Diagnostics</bridgehead>
&DIAGNOSTICS;
</sect2>
</sect1>
<!-- =================== INSTR ====================== -->
<sect1 id='tool-ref.instr'><title>&INSTR;</title>
<para>&INSTR; — offline class instrumentor.</para>
<sect2 id='tool-ref.instr.description'><title>Description</title>
<para>&INSTR; is &PROD;'s offline class instrumentor. It adds bytecode
instrumentation to all classes found in an <link
linkend="tool-ref.instr.instrpath.ANT">instrumentation
path</link> that also pass through user-provided coverage
filters. Additionally, it produces the <glossterm linkend='mdata'>class
metadata</glossterm> file necessary for associating <glossterm
linkend='rdata'>runtime coverage data</glossterm> with the original class
definitions during coverage report generation.</para>
<formalpara id='tool-ref.instr.instrpath'><title>Instrumentation path.</title>
<para>Note that the classes to be instrumented are taken from a
path element that is exactly like the kind taken by normal JDK tools
and ANT tasks: it is a list of directories (containing
<filename>.class</filename> files) and
<filename>.jar</filename>/<filename>.zip</filename>
archives (specified as an arbitrary number of
<link
linkend='tool-ref.instr.instrpath.ANT'><option>instrpath</option></link>
(<link linkend='tool-ref.instr.ip.cmdline'><option>-ip</option></link>) options). All
non-existent or duplicate entries in the instrumentation path are
effectively ignored during processing.
<note><title><option>Class-Path</option> manifest entries</title>
<simpara>Note that &INSTR; processes <option>Class-Path</option>
entries in the manifests of class archives that it
encounters. This is by design and is the desirable behavior (especially in the
overwrite and fullcopy output modes), but care needs to be taken
to avoid processing unintended implicit path segments.</simpara>
</note>
</para>
</formalpara>
<formalpara id='tool-ref.instr.outmodes'><title>Output modes.</title>
<para>To accomodate different build and testsuite designs
&INSTR; has
three different modes for how it outputs instrumented classes:
<variablelist>
<varlistentry>
<term><option>copy</option></term>
<listitem>
<simpara>In this mode, all instrumented classes are output
to a single destination directory, regardless of whether the source
classes came from a directory or an archive. Furthemore,
only the classes and archive entries that are in the
<glossterm linkend='instr.set'>instrumentation
set</glossterm> are written out. The idea here is to process
just the necessary classes in as few disk I/O operations as
possible.</simpara>
<simpara>For coverage-enabled application/testsuite runs
the destination directory needs to be placed in the
classpath ahead of the original classes. If this is
inconvenient (say, because you need to package classes in
archives before you can run), the <option>overwrite</option>
mode might be a better option.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>overwrite</option></term>
<listitem>
<simpara>This mode is similar to <option>copy</option>,
except it overwrites the original class and archive
files. This is ideal as a pre-packaging step turned on only
when coverage-enabled application/testsuite runs are
needed. Its advantage over the <option>copy</option> mode is
that it can do jar-to-jar processing and eliminates the need
to prepend a special output directory to the classpath. Its
disadvantage is the extra CPU and disk I/O times needed to
duplicate archive entries that are not being
instrumented<footnote><simpara>ZIP file format does not
allow incremental updates. For every class archive in the
instrumentation path, to replace the selected entries
with their instrumented version &PROD; has to create a temporary
archive that eventually replaces the original. This
implies that all zip entries not being instrumented must be
copied from one archive file to the
other.</simpara></footnote>.</simpara>
<simpara></simpara><!-- needed to offset the footnote above -->
</listitem>
</varlistentry>
<varlistentry>
<term><option>fullcopy</option></term>
<listitem>
<simpara>This mode is a hybrid between <option>copy</option>
and <option>overwrite</option>. It offers the convenience of
mixed individual class file and jar-to-jar processing
without having to overwrite the original content. In this
mode, the destination directory is split into two subdirectories,
<filename>classes</filename> and <filename>lib</filename>,
which accept instrumented class files and instrumented class
archives, respectively.</simpara>
<simpara>Note that because in this mode
&INSTR;
has to copy the most content (both files and archive entries
that are not being instrumented), this mode could be the
slowest of the three. The exact performance behavior
depends on the relative speeds of your CPU and I/O
subsystems and on the relative content mixes between class files and class
archives in the input.</simpara>
</listitem>
</varlistentry>
</variablelist>
By design, in all output modes that can do jar-to-jar processing
&INSTR; does not
compress the instrumented zip entries in the output archives. This saves CPU
time needed for doing compression, usually at an acceptable cost in the
increased disk space taken by the affected archive files.
</para>
</formalpara>
<formalpara id='tool-ref.instr.mdata'><title>Class coverage metadata.</title>
<para>An important byproduct of class instrumentation is <glossterm
linkend='mdata'>class metadata</glossterm>. As described in more
detail elsewhere, &PROD; coverage is based on instrumenting basic
bytecode blocks. Every instrumentation run outputs a compact
representation of data necessary to associate coverage of an
individual basic block with its parent method and class as well as
the original Java source lines that map to this basic basic (there
is a metadata entry for every class in the instrumentation class set). Class
metadata from each offline instrumentation run needs to be saved in a disk
file, because it will be required for coverage stats computation
and coverage report generation.</para>
</formalpara>
<para>Note that when &INSTR; writes metadata into a file, it will by
default <emphasis>merge</emphasis> incoming metadata into the
existing data in the destination file (if it exists). This behavior
is also necessary to support <link linkend='instr.incremental'><emphasis>incremental
instrumentation</emphasis></link>, as described shortly.</para>
<formalpara id='tool-ref.instr.mdatamerging'><title>Class metadata merging.</title>
<para>To avoid any ambiguities, it is necessary to completely specify
how &INSTR;
resolves duplicate data during instrumentation path processing:
<orderedlist>
<listitem>
<simpara>During a given <glossterm linkend='instr.run'>instrumentation run</glossterm>, all directory
and archive entries in the instrumentation path are
processed left-to-right. All duplicates (defined as entries
with the same canonical file pathnames) are skipped. As
noted above, valid <option>Class-Path</option> manifest
entries are also processed, in the order they are
discovered. This sequence is thus the same as it would be
for classloading lookup if the instrumentation path were
used as a classpath.</simpara>
</listitem>
<listitem>
<simpara>It is still possible that during the same
instrumentation run identical class names are encountered
(e.g., if the same class name shows up in differently named
archives). To stay consistent with classloading lookup rules
(the first class definition in a classpath wins),
&INSTR;
will instrument and emit metadata only for the first class
definition it encounters.</simpara>
</listitem>
<listitem>
<simpara>Finally, it is possible that multiple metadata entries for
idential class names are brought together when metadata from
<emphasis>independent</emphasis> instrumentation runs is merged together. The
rule here is that the <emphasis>last</emphasis> metadata
entry wins. The last entry is defined as either the last one
merged into a given metadata file or (in the case of multiple
files) contained in the last file in a given input file
set.</simpara>
</listitem>
</orderedlist>
</para>
</formalpara>
<para>The last point is best illustrated with an example. If both
<filename>coverageA.em</filename> and
<filename>coverageB.em</filename> contain metadata for class
<classname>MyClass</classname>:</para>
<screen><![CDATA[
>java ]]>∏<![CDATA[ instr -ip ... -d coverageA.em ...
>java ]]>∏<![CDATA[ instr -ip ... -d coverageB.em ...]]></screen>
<simpara>then the definition in <filename>coverageB.em</filename>
wins in all these cases:</simpara>
<screen><![CDATA[
>java ]]>∏<![CDATA[ report -in coverageA.em -in coverageB.em ...
>java ]]>∏<![CDATA[ report -in coverageA.em,coverageB.em ...
>java ]]>∏<![CDATA[ merge -in coverageA.em -in coverageB.em ...]]></screen>
<simpara>Similar rules apply to &PROD; ANT tasks.</simpara>
<formalpara id='instr.incremental'><title>Incremental instrumentation and metadata merging.</title>
<para>As is common knowledge, when working with
<command>javac</command>, either from command line or via ANT's
<command><javac></command> task, only the classes that were
modified since the last compilation get re-compiled. This is incredibly
convenient for an individual developer, as it makes a complex
product build incremental: small changes to the source code
results in quick incremental compiles. This is indispensable for
the "code some—test some—repeat" approach to software development.</para>
</formalpara>
<para>&PROD; can be used such that it fully preserves the
incremental nature of a build. The key to this is how
class metadata is merged when it is output to the same file. Suppose
a developer executes the following actions (&PROD; command line
tools are used here for compactness, but the same is possible with
an &PROD;-enhanced ANT build):</para>
<screen>>javac -g -d classes src/my/java/sources/*.java
>java ∏ instr -ip classes ...
<emphasis>... edit some sources ...</emphasis>
>javac -g -d classes src/my/java/sources/*.java
<emphasis>... only the changed source files get re-compiled ...</emphasis>
>java ∏ instr -ip classes ...
<emphasis>... only the re-compiled class files get re-instrumented ...</emphasis></screen>
<para>In this case &INSTR; was either in <option>copy</option>
or in <option>overwrite</option> mode and it implicitly used the same
default coverage metadata repository file,
<filename>coverage.em</filename>, for each
instrumentation run. In the <option>copy</option> mode, &INSTR;
instruments only the class files whose instrumented versions in the
output directory are older than their
<command>javac</command>-produced original versions. In
the <option>overwrite</option> mode case, &INSTR; will instrument
(and overwrite) only the classes that are not already instrumented
(because those would be the classes recently recompiled by
<command>javac</command>). All later metadata entries written to
<filename>coverage.em</filename> override any earlier definitions
and it all works out correctly (and very fast).</para>
<para>Because the metadata is always up-to-date in this scenario,
the developer can run his/her tests and look at coverage stats at
any time he/she runs the tests, without doing an expensive
rebuild of the entire project.</para>
<note><title>Runtime coverage data merging</title>
<simpara>Note that the rules for merging <glossterm
linkend='rdata'>runtime coverage data</glossterm> are different: the
data from different coverage runs is assumed to correspond to the
same class definitions (in most cases &PROD; will abort with an error
if it detects a mismatch). Basic block coverage is merged such that the
final coverage profile is a <emphasis>union</emphasis> of all merged
profiles.</simpara>
</note>
<para>The following table summarizes the major differences between
&INSTR; output modes:
<table frame='all' tocentry='1'><title>&INSTR; output mode summary</title>
<tgroup cols='4' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth='1*'/>
<colspec colname='c2' colwidth='1*' align='center'/>
<colspec colname='c3' colwidth='1*' align='center'/>
<colspec colname='c4' colwidth='2*'/>
<thead>
<row>
<entry>Mode</entry>
<entry>Supports jar-to-jar processing</entry>
<entry>Supports incremental instrumentation</entry>
<entry>Output behavior</entry>
</row>
</thead>
<tbody>
<row>
<entry><option>copy</option></entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>All instrumented classes are written to a single
destination directory (only instrumented entities are
written out), regardless of whether they come from
class files or class archives.</entry>
</row>
<row>
<entry><option>overwrite</option></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Instrumented (and only instrumented) classes are
overwritten in-place. Instrumented (and only instrumented) archive
entries are updated in their archives.</entry>
</row>
<row>
<entry><option>fullcopy</option></entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>All (instrumented or not) class files are written
to a <filename>classes</filename> subdirectory of the
destination directory. All (instrumented or not) class
archives are written out to a <filename>lib</filename>
subdirectory of the destination directory.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<formalpara><title>Internal &PROD; properties that affect class instrumentation.</title>
<para>Several property settings affect &INSTR; behavior:
<itemizedlist>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.do_suid_compensation'/></phrase></simpara>
</listitem>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.exclude_synthetic_methods'/></phrase></simpara>
</listitem>
<listitem>
<simpara><phrase role='property'><xref linkend='prop-ref.instr.exclude_bridge_methods'/></phrase></simpara>
</listitem>
</itemizedlist>
</para>
</formalpara>
<simpara>Most of these should normally be left with their default
values. <phrase role='property'><xref linkend='prop-ref.instr.do_suid_compensation'/></phrase>
can be set to <option>false</option> to gain extra instrumentation
processing speed when runtime execution does not involve class
de-serialization from existing files or serialization across
JVMs.</simpara>
<!-- TODO: define what gets instrumented -->
</sect2>
<sect2 id='tool-ref.instr.ANT'><title>ANT usage</title>
<bridgehead>Parameters specified as attributes</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task attributes</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.instr.instrpath.ANT'>
<entry valign='top'><option>instrpath</option></entry>
<entry>A <citetitle>path-like structure</citetitle>
specifying the instrumentation path to use.</entry>
<entry>Either this attribute, or <option>instrpathref</option>
attribute, or at least one nested
<option><instrpath></option> element must be present.</entry>
</row>
<row id='tool-ref.instr.instrpathref.ANT'>
<entry valign='top'><option>instrpathref</option></entry>
<entry>Same as <option>instrpath</option>, but given as a reference to a
path defined elsewhere.</entry>
<entry>Either this attribute, or <option>instrpath</option>
attribute, or at least one nested
<option><instrpath></option> element must be present.</entry>
</row>
<row id='tool-ref.instr.destdir.ANT'>
<entry valign='top'><option>destdir</option>, <option>outdir</option></entry>
<entry>The location to store instrumented class files (in
<option>fullcopy</option> mode instrumented classes are stored in
<option>destdir</option><filename>/classes</filename> and
instrumented archives are stored in
<option>destdir</option><filename>/lib</filename>
subdirectories, respectively). Ignored if <option>mode='overwrite'</option>.</entry>
<entry>Yes, unless <option>mode='overwrite'</option></entry>
</row>
<row id='tool-ref.instr.metadatafile.ANT'>
<entry valign='top'><option>metadatafile</option>, <option>outfile</option></entry>
<entry>The location to store class coverage metadata (default:
file <filename>coverage.em</filename> in the current
directory). Neither particular file name nor extension are
required.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.instr.merge.ANT'>
<entry valign='top'><option>merge</option></entry>
<entry>Indicates whether the metadata should be merged into
the destination <option>metadatafile</option>, if any
(default: <option>true</option>). Any existing data is
clobbered otherwise.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.instr.mode.ANT'>
<entry valign='top'><option>mode</option></entry>
<entry>Specifies the instrumentation output mode. Valid values
for this property are:<itemizedlist>
<listitem>
<simpara><option>copy</option> (default): copy only instrumented
class files and archive entries into
<option>destdir</option> directory.</simpara>
</listitem>
<listitem>
<simpara><option>overwrite</option>: overwrite input
class files and archives.</simpara>
</listitem>
<listitem>
<simpara><option>fullcopy</option>: copy all
(instrumented or not) class files and archives to
<option>destdir</option><filename>/classes</filename>
and <option>destdir</option><filename>/lib</filename>, respectively.</simpara>
</listitem>
</itemizedlist>
See <xref linkend='tool-ref.instr.description'/> for more details.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.instr.filter.ANT'>
<entry valign='top'><option>filter</option></entry>
<entry>Adds an instrumentation filter. See <xref linkend='instrset.filters'/> for
general description of &PROD;'s instrumentation filters and <xref linkend='filtersyntax.ANT'/>
specifically for ANT syntax.</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<bridgehead>Parameters specified as nested elements</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Element</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task nested elements</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.instr.nested.instrpath.ANT'>
<entry valign='top'><option><instrpath></option></entry>
<entry>A <citetitle>path-like structure</citetitle> that specifies the instrumentation path to use.</entry>
<entry>Either <option>instrpath</option> attribute, or <option>instrpathref</option>
attribute, or at least one nested
<option><instrpath></option> element must be present.</entry>
</row>
<row id='tool-ref.instr.nested.filter.ANT'>
<entry valign='top'><option><filter></option></entry>
<entry>Adds an instrumentation filter. See <xref linkend='instrset.filters'/> for
general description of &PROD;'s instrumentation filters and <xref linkend='filtersyntax.ANT'/>
specifically for ANT syntax.</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<formalpara><title><option><instrpath></option> nested elements</title>
<para><option><instrpath></option> is a <ulink
url='http://ant.apache.org/manual/using.html#path'><citetitle>path-like
structure</citetitle></ulink> used to select class files and
archives to be processed for instrumentation. If a duplicate class
name is encountered during a single instrumentation pass, only
the first class definition will be added to the <glossterm
linkend='mdata'>class metadata</glossterm> emitted during this
instrumentation path. See <xref linkend='tool-ref.instr.mdatamerging'/> for more details. <!-- TODO: mention that
attributes get assigned after nested elements --> </para>
</formalpara>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>In-place instrument a certain subset of already compiled classes
using <option>overwrite</option> mode and several coverage filters:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<instr instrpathref="${out.dir}/classes"
mode="overwrite"
>
<!-- always exclude every class with a "Test" in the name: -->
<filter excludes="*Test*" />
<!-- don't instrument everything in "${out.dir}/classes",
only the stuff I am working on now: -->
<filter file="myincludes.txt" />
<!-- additional ANT command line hook: -->
<filter value="${emma.filter}" />
</instr>
</emma>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Don't overwrite compiled classes that later need to go into official
release jars (stay in <option>copy</option> mode). However, use incremental
instrumentation for fast personal testing:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<instr instrpathref="${out.dir}/classes"
outdir="${out.dir}/classes-instrumented"
merge="yes"
filter="${emma.filter}"
/>
</emma>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Take all jars already produced by the product build and make test
(coverage-enabled) copies of them:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<instr mode="fullcopy"
outdir="${out.instr.dir}"
merge="no"
filter="${emma.filter}"
>
<instrpath>
<fileset dir="${out.dir}" includes="**/*.jar" />
</instrpath>
</instr>
</emma>]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='tool-ref.instr.cmdline'><title>Command line usage</title>
<bridgehead>Synopsis</bridgehead>
<!-- TODO: best opt order -->
<cmdsynopsis>
<command>java ∏ instr</command>
<arg choice='req' rep='repeat'>-ip <replaceable>instrumentation path</replaceable></arg>
<arg choice='opt'>-d <replaceable>directory</replaceable></arg>
<arg choice='opt'>-out <replaceable>metadata file</replaceable></arg>
<arg choice='opt'>-merge <replaceable>boolean</replaceable></arg>
<arg choice='opt'>-m <replaceable>output mode</replaceable></arg>
<arg choice='opt' rep='repeat'>-ix <replaceable>filter patterns</replaceable></arg>
<sbr/>
<arg choice='opt'><option><link linkend='commonoptions.cmdline'>common options</link></option></arg>
</cmdsynopsis>
<bridgehead>Options</bridgehead>
<simpara>[<option><link linkend='commonoptions.cmdline'>common command line options</link></option>]</simpara>
<variablelist>
<varlistentry id='tool-ref.instr.ip.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-ip, -cp, -instrpath <replaceable>instrumentation path</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option sets the
instrumentation path to use. Besides the OS-specific separator
character, individual path segments can also be separated
with commas.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.instr.d.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-d, -dir, -outdir <replaceable>directory</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>The location to store instrumented class files (in
<option>fullcopy</option> mode instrumented classes are stored in
<option>destdir</option><filename>/classes</filename> and
instrumented archives are stored in
<option>destdir</option><filename>/lib</filename>
subdirectories, respectively). Ignored if
<option>-m</option> is <option>overwrite</option>.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.instr.out.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-out, -outfile <replaceable>metadata file</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>The location to store class coverage metadata (default:
file <filename>coverage.em</filename> in the current
directory). Neither particular file name nor extension are
required.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.instr.merge.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-merge (<constant>y[es]</constant>|<constant>n[o]</constant>)</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This flag indicates whether the metadata should be merged into
the destination <option>-out</option> file, if any
(default: <option>true</option>). Any existing data is
clobbered otherwise.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.instr.m.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-m, -outmode (<constant>copy</constant>|<constant>overwrite</constant>|<constant>fullcopy</constant>)</option></arg>
</cmdsynopsis>
</term>
<listitem>
<para>Specifies the instrumentation output mode. Valid values
for this property are:<itemizedlist>
<listitem>
<simpara><option>copy</option> (default): copy only instrumented
class files and archive entries into
<option>destdir</option> directory.</simpara>
</listitem>
<listitem>
<simpara><option>overwrite</option>: overwrite input
class files and archives.</simpara>
</listitem>
<listitem>
<simpara><option>fullcopy</option>: copy all
(instrumented or not) class files and archives to
<option>destdir</option><filename>/classes</filename>
and <option>destdir</option><filename>/lib</filename>, respectively.</simpara>
</listitem>
</itemizedlist>
See <xref linkend='tool-ref.instr.description'/> for more
details.
</para>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.instr.ix.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-ix, -filter <replaceable>filter patterns</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option adds an instrumentation
filter. See <xref linkend='instrset.filters'/> for
general description
of &PROD; coverage filters and <xref linkend='filtersyntax.cmdline'/>
specifically for command line syntax.</simpara>
</listitem>
</varlistentry>
</variablelist>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>In-place instrument a certain subset of already compiled classes
using <option>overwrite</option> mode and several coverage filters:
<screen><![CDATA[
>java emma instr -m overwrite -ip out/classes -ix -*Test* -ix @myfilters.txt]]></screen>
</para>
</listitem>
<listitem>
<para>Don't overwrite compiled classes that later need to go into official
release jars (stay in <option>copy</option> mode). However, use incremental
instrumentation for fast personal testing:
<screen><![CDATA[
>java emma instr -merge y -ip out/classes -d out/classes-instrumented]]></screen>
</para>
</listitem>
<listitem>
<para>Take all jars already produced by the product build and make test
(coverage-enabled) copies of them:
<screen><![CDATA[
>java emma instr -m fullcopy -merge no -ip out/Product.jar -d out-instrumented/]]></screen>
</para>
</listitem>
</itemizedlist>
<bridgehead>Diagnostics</bridgehead>
&DIAGNOSTICS;
</sect2>
</sect1>
<!-- =================== REPORT ====================== -->
<sect1 id='tool-ref.report'><title>&REPORT;</title>
<para>&REPORT; — offline coverage report generator.</para>
<sect2><title>Description</title>
<para>&REPORT; is &PROD;'s offline coverage report generator. It
reads in an arbitrary number of data files containing <glossterm
linkend='mdata'>class metadata</glossterm> and <glossterm
linkend='rdata'>runtime coverage data</glossterm> and generates one or
several coverage reports of desired types. Several aspects of coverage
reporting (detail level, column order, column sorting, coverage metrics
failure markup, etc) can be customized for a given report type.</para>
<formalpara><title>What is reported on.</title>
<para>Each invocation of &REPORT; requires a set of input
<glossterm linkend='mdata'>metadata</glossterm> and <glossterm
linkend='rdata'>runtime coverage data</glossterm> files. &PROD;
coverage stats are derived exclusively from the classes that
appear in the combined class metadata as represented by this
input. To put it differently, a coverage report can reflect as
much as the state of the entire product codebase or as little as
one Java package or API being worked on by a given developer at
the moment.</para>
</formalpara>
<formalpara id='tool-ref.reportdepth'><title>Report depth.</title>
<para>To understand &PROD;'s approach to generating coverage
reports, the following paradigm should be kept in mind:</para>
</formalpara>
<para>
<itemizedlist>
<listitem>
<simpara>a given coverage report covers all entities in the <glossterm linkend='instr.set'>instrumentation
set</glossterm>, referred to as &ALLCLASSES; in the reports</simpara>
</listitem>
<listitem>
<simpara>&ALLCLASSES; entity contains Java packages</simpara>
</listitem>
<listitem>
<simpara>[for classes compiled with full debug info] Java
packages contain Java source files</simpara>
</listitem>
<listitem>
<para>
<itemizedlist>
<listitem>
<simpara>[for classes compiled with full debug info]
Java source files contain Java classes (in general, more
than one)</simpara>
</listitem>
<listitem>
<simpara>[for classes compiled without full debug info]
Java packages contain Java classes </simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<simpara>Java classes contain methods (which, in turn,
could be broken down into basic blocks)</simpara>
</listitem>
</itemizedlist>
(The reason &PROD; makes a distinction between classes with and
without full debug info is that without the
<classname>SourceFile</classname> attribute in all input classes it
is in general impossible to make the association between classes and
their source files and that in turn impacts how metrics
like <glossterm linkend='coverage.line'>line coverage</glossterm>
are rolled up. The above hierarchy is easier to understand if you
realize that without the full debug info the source file hierarchy
level is absent.)</para>
<para>Correspondingly, &REPORT; calculates and presents coverage metrics in a way
that allows for drilling down into data in a top-down fashion,
starting with &ALLCLASSES;
and going all the way to the level of individual methods and
source lines (in the HTML report). Coverage metrics are rolled up at the levels of
individual methods, classes, source files, packages, and for the
entire instrumentation set (&ALLCLASSES;). The concept of "report
depth" represents how deep you are in this hierarchy.</para>
<para>Different report types produced by &REPORT; differ in
how they reflect this data hierarchy:
<itemizedlist>
<listitem>
<simpara>The plain text report is a low-overhead report type for
quick coverage summary viewing and processing by tools like
<command>grep</command> and <command>Perl</command>. It starts
with an &ALLCLASSES; summary and progressively adds further
drill-down sections. Because a columnar plain text format is
limited in how well it can present hierarchical data, it is
recommended that for report depths beyond <option>all</option>
and <option>package</option> you use the HTML report instead.</simpara>
</listitem>
<listitem>
<simpara>The HTML report can provide the most detail and is
intended for human viewing. It starts with an &ALLCLASSES;
summary page and for larger report depths links it to
package summary pages and then further to individual source
file and class summary pages. Source/class summary pages can
further embed source files and show method coverage rollups as
well as highlight individual source line coverage states.</simpara>
</listitem>
<listitem>
<simpara>The XML report exits for integration purposes and
leverages the tree structure of an XML document to most
truthfully represent the above-mentioned data hierarchy.</simpara>
</listitem>
</itemizedlist>
Because generating certain report types for very large projects can
be time-consuming, reducing the default report depth is a good way
to limit the amount of detail that is generated, a useful feature
for individual development work.</para>
<para>Valid values for a report depth are <option>all</option>,
<option>package</option>, <option>source</option>,
<option>class</option>, and <option>method</option>. In general, a
certain report depth value implies the level of detail that includes
the summary for all items at that level as well as
coverage breakdown summaries for their children. The amount of information rendered
for a given depth value is always inclusive of
lesser depth values, so increasing the report depth always increases
the amount of details that is rendered. As a special case, when full debug info is
available, <option>class</option> is equivalent to
<option>source</option>.</para>
<formalpara id='tool-ref.reportunits'><title>Report units.</title>
<para>&PROD; coverage metrics could be
<emphasis>unweighted</emphasis> or <emphasis>weighted</emphasis>,
that is derived from basic block coverage where each block
counts either with an equal weight or with a weight proportional
to the number of Java bytecode instructions in it. The default
&REPORT; behavior is to use weighted metrics. This includes all
metrics that are sensitive to basic block content: line and block
coverage. Weighted basic block coverage is a recommended metric for
all situations, because it can simulate line coverage when no debug
information has been compiled into application classes. If
desired, the traditional (unweighted) metrics could be
selected using the <link
linkend='tool-ref.report.units.ANT'>units</link> option.</para>
</formalpara>
<formalpara><title>Coverage metrics.</title>
<para>A very useful feature of HTML and plain text reports created
by &REPORT; is the ability to highlight entities that fail a given
<link linkend='tool-ref.report.metrics.ANT'>coverage
metric</link>. The plain text report does it by appending a "!"
to a failing coverage metric and the HTML report highlights those
in red. Combined with ability to <link
linkend='tool-ref.report.sort.ANT'>sort</link> report columns, this feature
allows an individual developer to zoom in to the
packages and classes that demand the most attention with respect
to coverage.</para>
</formalpara>
<formalpara id='report.sourcepath'><title>Sourcepath and source linking.</title>
<para>Although &PROD; coverage calculations are based on basic
block coverage profiling, &REPORT; can also map block coverage to
Java source file lines. If the HTML report generator is set
to <option>method</option> depth and is configured with a valid
source path and the instrumented classes were compiled with enough
debug information, the generator will embed source files in the
source file/class summary report pages and highlight covered/not
covered lines accordingly.
<note><title>Sourcepath and coverage stats</title>
<simpara>Referencing the original Java source files is
optional during coverage report generation and does not affect
how &PROD; coverage stats are computed (these stats are based
entirely on the <glossterm linkend='mdata'>class
metadata</glossterm> and the debug info available in the
<filename>.class</filename> data at the instrumentation
time). However, to avoid report generation errors it is your
responsibility to ensure that the
versions of Java sources used for reporting are the same as
the ones used during instrumentation.</simpara>
</note>
</para>
</formalpara>
<!-- TODO: different coverage types and report.columns -->
<!-- TODO: what is considered executable -->
<!-- TODO: how line coverage is rolled up -->
</sect2>
<sect2 id='tool-ref.report.ANT'><title>ANT usage</title>
<bridgehead>Parameters specified as attributes</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task attributes</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.sourcepath.ANT'>
<entry valign='top'><option>sourcepath</option></entry>
<entry>An optional source path to use for report
generation (a <citetitle>path-like
structure</citetitle>). It is interpreted as a list of
directories (separated by the OS-specific classpath
separator or comma) containing <filename>.java</filename>
source files. The local path names within each directory
should reflect class package names. (Currently, only the HTML report
generator uses this data, and only at
<option>method</option> report depth.)</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.sourcepathref.ANT'>
<entry valign='top'><option>sourcepathref</option></entry>
<entry>Same as <option>sourcepath</option>, but given as a
reference to a path defined elsewhere.</entry>
<entry>No</entry>
</row>
<!-- TODO: make the order is the same as for nested configs -->
<row id='tool-ref.report.units.ANT'>
<entry valign='top'><option>units</option></entry>
<entry>Specifies whether weighted or unweighted coverage
metrics are calculated. Valid values are:
<itemizedlist>
<listitem><simpara><option>instr</option> (default):
use metrics weighted by bytecode instruction count;</simpara></listitem>
<listitem><simpara><option>count</option>:
use traditional metric definitions (each basic block
has equal weight).</simpara></listitem>
</itemizedlist>
</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.depth.ANT'>
<entry valign='top'><option>depth</option></entry>
<entry>Specifies the amount of detail to be included in
the generated coverage reports, as described in <xref
linkend='tool-ref.reportdepth'/>. Valid values (in order
of increasing level of detail) are:
<itemizedlist>
<listitem><simpara><option>all</option></simpara></listitem>
<listitem><simpara><option>package</option></simpara></listitem>
<listitem><simpara><option>source</option></simpara></listitem>
<listitem><simpara><option>class</option></simpara></listitem>
<listitem><simpara><option>method</option></simpara></listitem>
</itemizedlist>
(default values are report type-specific, see below)
</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.columns.ANT'>
<entry valign='top'><option>columns</option></entry>
<entry>Specifies which report columns and in which order
to use for report generation, as a comma-separated list of
column ids. Valid column ids are the name of the item
reported on and various types of coverage:
<option>name</option>, <option>class</option>,
<option>method</option>, <option>block</option>, and
<option>line</option>. Coverage types that are not
available for a given item type and debug info level are
automatically ignored. Reports can use only a subset of
all possible columns (and different report types can use
different subsets). Duplicate column names are
ignored. Setting this attribute is the same as setting the
<phrase role='property'><xref
linkend='prop-ref.report.columns'/></phrase> property for
all report types (default values are report type-specific,
see below).</entry> <entry>No</entry>
</row>
<row id='tool-ref.report.sort.ANT'>
<entry valign='top'><option>sort</option></entry>
<entry>Specifies report column sorting order, as a
comma-separated list of column ids prefixed with
<quote>+</quote> for ascending or <quote>-</quote> for
descending directions. The first column id is the primary
sort and subsequent column ids are secondary sorts, in the
order given. Only the column ids specified by
<option>columns</option> attribute are considered.
Setting this attribute is the same as setting the <phrase
role='property'><xref
linkend='prop-ref.report.sort'/></phrase> property for all
report types (default:
<option>+block,+name,+method,+class</option>).</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.metrics.ANT'>
<entry valign='top'><option>metrics</option></entry>
<entry>Specifies the threshold coverage metric values for
a given set of columns (all coverage percentages that are
below a given threshold are marked up in the report types
that support this). The value is a comma-separated list of
column id-value pairs, with the value being the minimum
required coverage percentage. Setting this attribute is
the same as setting the <phrase role='property'><xref
linkend='prop-ref.report.metrics'/></phrase> property for
all report types (default:
<option>method:70,block:80,line:80,class:100</option>).</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.encoding.ANT'>
<entry valign='top'><option>encoding</option></entry>
<entry>Sets the charset id for report output files (this
is best done at the individual report type level). Setting
this attribute is the same as setting the <phrase
role='property'><xref
linkend='prop-ref.report.out.encoding'/></phrase> property
for all report types (default values are report
type-specific, see below).</entry> <entry>No</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<bridgehead>Parameters specified as nested elements</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Element</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task nested elements</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.nested.infileset.ANT'>
<entry valign='top'><option><infileset></option>, <option><fileset></option></entry>
<entry>A <citetitle>FileSet</citetitle> that selects a set
of <glossterm linkend='mdata'>metadata</glossterm> and
<glossterm linkend='rdata'>coverage data</glossterm> files
that form the basis of coverage calculations in the
generated report(s). It is an error not to include any
metadata or any coverage data within this set of files.</entry>
<entry>Yes</entry>
</row>
<row id='tool-ref.report.nested.sourcepath.ANT'>
<entry valign='top'><option><sourcepath></option></entry>
<entry>A <citetitle>path-like structure</citetitle> that specifies an optional
source path to use for HTML report generation.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.nested.txt.ANT'>
<entry valign='top'><option><txt></option></entry>
<entry>Instructs <command><report></command> to generate a
plain-text coverage report. The report can be further
customized as shown below.</entry>
<entry>At least one of <option><txt></option>,
<option><html></option>,
<option><xml></option> is required</entry>
</row>
<row id='tool-ref.report.nested.html.ANT'>
<entry valign='top'><option><html></option></entry>
<entry>Instructs <command><report></command> to generate an
HTML coverage report. The report can be further
customized as shown below.</entry>
<entry>At least one of <option><txt></option>,
<option><html></option>,
<option><xml></option> is required</entry>
</row>
<row id='tool-ref.report.nested.xml.ANT'>
<entry valign='top'><option><xml></option></entry>
<entry>Instructs <command><report></command> to generate an
XML coverage report. The report can be further
customized as shown below.</entry>
<entry>At least one of <option><txt></option>,
<option><html></option>,
<option><xml></option> is required</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<formalpara><title><option><infileset></option> nested elements.</title>
<para><option><infileset></option> nested elements are configured as
any other <ulink
url='http://ant.apache.org/manual/CoreTypes/fileset.html'><citetitle>FileSet</citetitle></ulink>
data type in ANT. Additionally, &PROD;'s version of
<citetitle>FileSet</citetitle> data type allows
<option>file</option> attribute in ANT versions earlier than
1.5.x (which is useful for selecting a single file by its known name without
using an explicit <citetitle>PatternSet</citetitle>).</para>
</formalpara>
<formalpara id='report.nestedsourcepath'><title><option><sourcepath></option> nested elements.</title>
<para><option><sourcepath></option> is a <ulink
url='http://ant.apache.org/manual/using.html#path'><citetitle>path-like
structure</citetitle></ulink> that can be used to point &REPORT;
to the location of your Java source files. If the
HTML report <link linkend='tool-ref.report.cfg.depth.ANT'>depth</link>
is set to <option>method</option> and the instrumented classes
were compiled with enough debug information, the report generator will
embed whichever source files it can find inside the HTML
report pages and highlight covered/not covered lines.</para>
</formalpara>
<formalpara id='report.nestedcfg'><title><option><txt></option>,
<option><html></option>, and <option><xml></option> nested elements.</title>
<para>These nested elements create plain text, HTML, and XML
coverage reports, respectively. At least one report type must be
specified (at most one configurator of any given report type
can be nested inside a given
<command><report></command>). All of them accept the same set of
report configuration attributes (if a particular attribute is not
specified for an element, its value is inherited
from the <command><report></command> parent. If the parent task
does not specify an attribute value either, the usual &PROD; <link linkend='prop-ref.lookup'>property inheritance
rules</link> determine the eventual value):</para>
</formalpara>
<para>
<informaltable frame='all' tocentry='0'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row id='tool-ref.report.cfg.units.ANT'>
<entry valign='top'><option>units</option></entry>
<entry>Overrides the coverage metric <link linkend='tool-ref.report.units.ANT'>units</link> for a given report
type. It is perhaps best to set this at the parent
<command><report></command> level, so that all
generated reports use consistent units.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.cfg.depth.ANT'>
<entry valign='top'><option>depth</option></entry>
<entry>Overrides the report <link linkend='tool-ref.report.depth.ANT'>depth</link> for a given report
type. The default values are:
<itemizedlist>
<listitem><simpara><option>txt</option> report: <option>all</option></simpara></listitem>
<listitem><simpara><option>html</option> report: <option>method</option></simpara></listitem>
<listitem><simpara><option>xml</option> report: <option>method</option></simpara></listitem>
</itemizedlist>
</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.cfg.columns.ANT'>
<entry valign='top'><option>columns</option></entry>
<entry>Overrides the report <link
linkend='tool-ref.report.columns.ANT'>column selection and order</link> for a given report
type.The default values are:
<itemizedlist>
<listitem><simpara><option>txt</option> report: <option>class,method,block,line,name</option></simpara></listitem>
<listitem><simpara><option>html</option> report: <option>name,class,method,block,line</option></simpara></listitem>
<listitem><simpara><option>xml</option> report: <option>name,class,method,block,line</option></simpara></listitem>
</itemizedlist></entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.cfg.sort.ANT'>
<entry valign='top'><option>sort</option></entry>
<entry>Overrides the report <link
linkend='tool-ref.report.sort.ANT'>column sort order</link> for a given report
type.</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.cfg.metrics.ANT'>
<entry valign='top'><option>metrics</option></entry>
<entry>Overrides the report <link
linkend='tool-ref.report.columns.ANT'>coverage metrics thresholds</link> for a given report
type. It is perhaps best to set this at the parent
<command><report></command> level, so that all
generated reports use consistent metrics.</entry>
<entry>No</entry>
</row>
<!-- this is one is not allowed at the parent level: -->
<row id='tool-ref.report.cfg.outfile.ANT'>
<entry valign='top'><option>outfile</option></entry>
<entry>Overrides the default report output file
location. <!-- TODO: how relative names are resolved -->
The default settings are:
<itemizedlist>
<listitem><simpara><option>txt</option> report: file <filename>coverage.txt</filename> in the current directory</simpara></listitem>
<listitem><simpara><option>html</option> report: file
<filename>coverage/index.html</filename> (note that
the HTML report is usually split over multiple files,
so it is best to specify a file pathname that is
inside a dedicated subdirectory)</simpara></listitem>
<listitem><simpara><option>xml</option> report: file <filename>coverage.xml</filename> in the current directory</simpara></listitem>
</itemizedlist>
</entry>
<entry>No</entry>
</row>
<row id='tool-ref.report.cfg.encoding.ANT'>
<entry valign='top'><option>encoding</option></entry>
<entry>Overrides the <link
linkend='tool-ref.report.encoding.ANT'>output file charset
encoding</link> used for a given report type. The default values are:
<itemizedlist>
<listitem><simpara><option>txt</option> report:
mirrors the <option>file.encoding</option> JRE system
property</simpara></listitem>
<listitem><simpara><option>html</option> report: <option>ISO-8859-1</option></simpara></listitem>
<listitem><simpara><option>xml</option> report: <option>UTF-8</option></simpara></listitem>
</itemizedlist>
</entry>
<entry>No</entry>
</row>
<!-- [generic property setter not documented publicly] -->
</tbody>
</tgroup>
</informaltable>
</para>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Generate plain text and XML report types, all with default settings:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<report >
<!-- collect all EMMA data dumps (metadata and runtime): -->
<infileset dir="${coverage.dir}" includes="*.em, *.ec" />
<txt />
<xml />
</report>
</emma>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Generate three report types, with common metrics and column
sorting, but with different report depth and column orderings:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<report sourcepath="${src.dir}"
sort="+block,+name,+method,+class"
metrics="method:70,block:80,line:80,class:100"
>
<infileset dir="${coverage.dir}" includes="*.em, *.ec" />
<!-- for every type of report desired, configure a nested
element; various report parameters
can be inherited from the parent <report>
and individually overridden for each report type:
-->
<txt outfile="${coverage.dir}/coverage.txt"
depth="package"
columns="class,method,block,line,name"
/>
<xml outfile="${coverage.dir}/coverage.xml"
depth="package"
/>
<html outfile="${coverage.dir}/coverage.html"
depth="method"
columns="name,class,method,block,line"
/>
</report>
</emma>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Generate an HTML report with some customization, load metadata and runtime
coverage data from a single session file, use a <dirset> to set the sourcepath:
<programlisting><![CDATA[
<emma enabled="${emma.enabled}" >
<report >
<infileset file="${coverage.dir}/coverage.es" />
<sourcepath>
<dirset dir="${basedir}" >
<include name="**/src" />
</dirset>
</sourcepath>
<html outfile="${coverage.dir}/index.html"
columns="name, method, line"
sort="+line, +name"
metrics="line:80"
/>
</report>
</emma>]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='tool-ref.report.cmdline'><title>Command line usage</title>
<bridgehead>Synopsis</bridgehead>
<cmdsynopsis>
<command>java ∏ report</command>
<arg choice='req' rep='repeat'>-in <replaceable>data files</replaceable></arg>
<arg choice='req' rep='repeat'>-r <replaceable>report types</replaceable></arg>
<arg choice='opt' rep='repeat'>-sp <replaceable>sourcepath</replaceable></arg>
<arg choice='opt'><option><link linkend='commonoptions.cmdline'>common options</link></option></arg>
</cmdsynopsis>
<bridgehead>Options</bridgehead>
<simpara>[<option><link linkend='commonoptions.cmdline'>common command line options</link></option>]</simpara>
<variablelist>
<varlistentry id='tool-ref.report.in.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-in, -input <replaceable>meta/coverage data files</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option selects a set
of <glossterm linkend='mdata'>metadata</glossterm> and
<glossterm linkend='rdata'>coverage data</glossterm> files
that form the basis of coverage calculations in the
generated report(s). It is an error not to include any
metadata or any coverage data within this set of files.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.report.r.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-r, -report (<constant>txt</constant>|<constant>html</constant>|<constant>xml</constant>)</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option selects report type(s) to be generated.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.report.sp.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-sp, -sourcepath <replaceable>list of source directories</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option sets the (optional) source path to use for report
generation. It is interpreted as a list of
directories (separated by the OS-specific classpath
separator or comma) containing <filename>.java</filename>
source files. The local path names within each directory
should reflect class package names. (Currently, only the HTML report
generator uses this data, and only at
<option>method</option> report depth.)</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>report generation options</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>Unlike its ANT equivalent,
<command>report</command> command line tool does not have
dedicated options for controlling coverage report generation. If necessary, they can be
set using generic <link
linkend='commonoptions.property.cmdline'>-D</link>, <link
linkend='commonoptions.properties.cmdline'>-properties</link>,
and other mechanisms.</simpara>
<para>So, for example, to change the default location of the
HTML report you would override the <phrase
role='property'><xref
linkend='prop-ref.report.out.file'/></phrase> property:
<screen><![CDATA[
>java emma report -Dreport.html.out.file=mydir/mycoverage.html ...]]></screen>
(<option>report.html.out.file</option> can be abbreviated to
<option>report.out.file</option> if the command generates
a single report type)</para>
</listitem>
</varlistentry>
</variablelist>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Generate plain text and XML report types, both with their default settings:
<screen><![CDATA[
>java emma report -r txt,xml -in coverage.em -in coverage.ec]]></screen>
</para>
</listitem>
<listitem>
<para>Generate the HTML report only, but override the default
output location:
<screen><![CDATA[
>java emma report -r html -in coverage.em,coverage.ec -sp src/ -Dreport.html.out.file=mycoverage/coverage.html]]></screen>
</para>
</listitem>
<listitem>
<para>Generate three report types, with common metrics and column
sorting, but with different report depth and column
orderings. Use <link
linkend='commonoptions.properties.cmdline'><option>-properties</option></link>
option to pull in a large number of report property overrides:
<screen><![CDATA[
>java emma report -r txt,xml,html -props my.properties -in coverage.em,coverage.ec -sp src/]]></screen>
where file <filename>my.properties</filename> contains:
<programlisting><![CDATA[
report.sort = +block,+name,+method,+class
report.metrics = method:70,block:80,line:80,class:100
report.depth = package
report.txt.out.file = coverage/coverage.txt
report.txt.columns = class,method,block,line,name
report.xml.out.file = coverage/coverage.xml
report.html.out.file = coverage/coverage.html
report.html.depth = method
report.html.columns = name,class,method,block,line]]></programlisting>
</para>
</listitem>
<listitem>
<para>Generate an HTML report with some customization, load metadata and runtime
coverage data from a single session file:
<screen><![CDATA[
>java emma report -r html -in coverage.es -sp src/ \
-Dreport.columns=name,method,line \
-Dreport.sort=+line,+name \
-Dreport.metrics=line:80]]></screen>
</para>
</listitem>
</itemizedlist>
<bridgehead>Diagnostics</bridgehead>
&DIAGNOSTICS;
</sect2>
</sect1>
<!-- =================== MERGE ====================== -->
<sect1 id='tool-ref.merge'><title>&MERGE;</title>
<para>&MERGE; — offline meta- and runtime coverage data compressor.</para>
<sect2><title>Description</title>
<para>&MERGE; is &PROD;'s offline meta- and runtime coverage data
compressor. It reads in an arbitrary number of data files
containing <glossterm linkend='mdata'>class metadata</glossterm> and/or <glossterm
linkend='rdata'>runtime coverage data</glossterm> and compresses all
of it into a single session data file.</para>
<formalpara><title>Why merge?</title>
<para>Despite the fact that all other &PROD; tools can do
in-memory merging of an arbitrary number of input data files,
there are valid reason for using &MERGE; tool:
<variablelist>
<varlistentry><term>keeping everything together</term>
<listitem>
<simpara>Coverage metrics for a particular application
could be determined by a large set of meta- and runtime
coverage data files, not necessarily collected in a single
application run. For example, a Swing client could run in
one JVM and a remoted server in another, possibly on a
different host machine. Or a testsuite
could be spread over a sequence of forked JVM processes.</simpara>
<simpara>Collecting all &PROD; data in a single file could
be a simple matter of convenience: such a <glossterm
linkend='sdata'>coverage session data</glossterm> file is
a memento of a particular state of application
coverage. Such a session data file
contains all the data necessary to regenerate all coverage
reports (for <link linkend='report.sourcepath'>source code
embedding</link> in a coverage report you
also need to preserve the particular versions of sources
used at the instrumentation time: a source revision control system is a
good solution for this).</simpara>
</listitem>
</varlistentry>
<varlistentry><term>data compaction</term>
<listitem>
<simpara>When merging data into existing files, for
reasons that have to do with performance and
making file writes as transactional as possible, &PROD;
tools use an append-like technique. Once a given data
record is written to a file, it is never overwritten
(rather, later data writes implicitly override it).
What this means is that &PROD;'s un-merged
data files may not always store data in the most compact way
possible. Processing them with &MERGE; eliminates wasted
file storage and recovers disk space.</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</formalpara>
</sect2>
<sect2 id='tool-ref.merge.ANT'><title>ANT usage</title>
<bridgehead>Parameters specified as attributes</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task attributes</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.merge.mergefile.ANT'>
<entry valign='top'><option>mergefile</option>, <option>outfile</option>, <option>tofile</option>, <option>file</option></entry>
<entry>Overrides the location to store merged data
(default: file <filename>coverage.es</filename> in the current
directory).</entry>
<entry>No.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<bridgehead>Parameters specified as nested elements</bridgehead>
<para>
<informaltable tocentry='0' frame='all'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Element</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry namest="c1" nameend="c2"
align="center">[<option><link
linkend='commonoptions.ANT'>common &PROD; task nested elements</link></option>]</entry>
<entry>No</entry>
</row>
<row id='tool-ref.merge.nested.infileset.ANT'>
<entry valign='top'><option><infileset></option>, <option><fileset></option></entry>
<entry>A <citetitle>FileSet</citetitle> that selects an
arbitrary mix of <glossterm linkend='mdata'>metadata</glossterm> and
<glossterm linkend='rdata'>coverage data</glossterm> to be
merged. <!-- TODO: link to merging rules for mdata and cdata --></entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<formalpara>
<title><option><infileset></option> nested elements</title>
<para><option><infileset></option> nested elements are configured as
any other <ulink
url='http://ant.apache.org/manual/CoreTypes/fileset.html'><citetitle>FileSet</citetitle></ulink>
data type in ANT. Additionally, &PROD;'s version of
<citetitle>FileSet</citetitle> data type allows
<option>file</option> attribute in ANT versions earlier than
1.5.x (which is useful for selecting a single file by its known name without
using an explicit <citetitle>PatternSet</citetitle>).</para>
</formalpara>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Collect all &PROD; metadata and runtime coverage data files
and merge them into a single session file:
<programlisting><![CDATA[
<emma>
<merge outfile="${coverage.dir}/coverage.es" >
<fileset dir="${coverage.dir}" includes="*.em, *.ec" />
</merge>
</emma>]]></programlisting>
</para>
</listitem>
<listitem>
<para>Compact a single data file:
<programlisting><![CDATA[
<emma>
<merge outfile="${coverage.dir}/coverage.es" >
<fileset file="${coverage.dir}/coverage.es" />
</merge>
</emma>]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id='tool-ref.merge.cmdline'><title>Command line usage</title>
<bridgehead>Synopsis</bridgehead>
<cmdsynopsis>
<command>java ∏ merge</command>
<arg choice='req' rep='repeat'>-in <replaceable>data files</replaceable></arg>
<arg choice='opt'>-out <replaceable>data file</replaceable></arg>
<arg choice='opt'><option><link linkend='commonoptions.cmdline'>common options</link></option></arg>
</cmdsynopsis>
<bridgehead>Options</bridgehead>
<simpara>[<option><link linkend='commonoptions.cmdline'>common command line options</link></option>]</simpara>
<variablelist>
<varlistentry id='tool-ref.merge.in.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain' rep='repeat'><option>-in, -input <replaceable>meta/coverage data files</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This <glossterm
linkend='repeatable'>repeatable</glossterm> option selects an
arbitrary mix of <glossterm linkend='mdata'>metadata</glossterm> and
<glossterm linkend='rdata'>coverage data</glossterm> files
to be merged.</simpara>
</listitem>
</varlistentry>
<varlistentry id='tool-ref.merge.out.cmdline'>
<term>
<cmdsynopsis>
<arg choice='plain'><option>-out, -outfile <replaceable>output merge data file</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>Overrides the location to store merged data
(default: file <filename>coverage.es</filename> in the current
directory).</simpara>
</listitem>
</varlistentry>
</variablelist>
<bridgehead>Examples</bridgehead>
<itemizedlist>
<listitem>
<para>Collect all &PROD; metadata and runtime coverage data files
and merge them into a single session file:
<screen><![CDATA[
>java emma merge -in coverage.em -in coverage.ec -out coverage.es]]></screen>
</para>
</listitem>
<listitem>
<para>Compact a single data file:
<screen><![CDATA[
>java emma merge -in coverage.es -out coverage.es]]></screen>
</para>
</listitem>
</itemizedlist>
<bridgehead>Diagnostics</bridgehead>
&DIAGNOSTICS;
</sect2>
</sect1>
<!-- =================== FILTERS ====================== -->
<sect1><title>Defining the instrumentation set</title>
<sect2 id="instrset.overview"><title>How &PROD; determines which classes get instrumented</title>
<!--
- what gets instrumented:paths and filters
- filter syntax
- metadata and coverage data merging
- instr output modes
- relevant instr properties
-->
<para>Although &PROD;'s instrumentation is very fast (it is usually
fast enough so that the overall processing time is dominated by file
I/O), the key to making &PROD; into an even faster tool for
individual development is to make &PROD; do just the
right amount of work, i.e. define the right <emphasis>instrumentation
set</emphasis> of classes.</para>
<para>Understanding what gets instrumented is
also important for another reason: &PROD; coverage reports are based
exclusively on the classes in the instrumentation set as implied by
coverage metadata.</para>
<formalpara><title>Instrumentation set.</title>
<para>The set of classes that get instrumented in a given
invocation of a tool like &INSTR; or &RUN; is determined by the
following rules:
<orderedlist numeration='lowerroman'>
<listitem>
<simpara>First, a set of classes <emphasis>eligible for
instrumentation</emphasis> is determined by an
<emphasis>instrumentation path</emphasis>. For &INSTR; this
is set via an <link
linkend='tool-ref.instr.instrpath'>explicit option</link>
and for &RUN; it is the same as the application
classpath. Note that only Java classes contain executable
code and are eligible for instrumentation: Java interfaces
are never instrumented by &PROD;<footnote><simpara>Strictly
speaking, Java interfaces can contain executable bytecode,
but it usually corresponds to field initializer expressions that
execute unconditionally when the interface is loaded.</simpara></footnote>.</simpara>
</listitem>
<listitem>
<simpara>Next, the set of eligible classes as determined by
the above step can be further narrowed down by a set of
coverage <link
linkend='instrset.filters'><emphasis>inclusion and exclusion
filters</emphasis></link>.</simpara>
</listitem>
<listitem>
<para>Finally,
<itemizedlist>
<listitem>
<simpara>in the offline processing mode, all remaining eligible
classes are in fact instrumented and added to the metadata;</simpara>
</listitem>
<listitem>
<para>in the on-the-fly processing mode, &RUN; behavior
with respect to the remaining eligible classes depends
on whether the <emphasis>full classpath scan mode</emphasis> (<link
linkend='tool-ref.run.fullmetadata.ANT'><option>fullmetadata</option></link>
(<link linkend='tool-ref.run.f.cmdline'><option>-f</option></link>)
option) is turned on:
<itemizedlist>
<listitem>
<simpara>by default, this mode is not on and
only the classes actually used by the
application are instrumented and added to
the coverage metadata (this happens on demand);</simpara>
</listitem>
<listitem>
<simpara>if this mode is on, all remaining
eligible classes are added to the metadata
(this happens before the application starts running).</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</orderedlist>
</para>
</formalpara>
<para>What this means in practice is that you choose the right
set of class directories and archives via the instrumentation path option and then narrow
it further down via a number of coverage filters, described next.</para>
</sect2>
<sect2 id='instrset.filters'><title>Coverage filters</title>
<formalpara><title>Wildcards.</title>
<para>&PROD; coverage filters are lists of familiar
<option>*</option>,<option>?</option>-wildcard class name
patterns:
<itemizedlist>
<listitem>
<simpara><emphasis>full</emphasis> Java class names are implied, with
<quote><option>.</option></quote>'s (dots) as Java package separators;</simpara>
</listitem>
<listitem>
<simpara>a <quote><option>*</option></quote> in a pattern stands for zero or
more class name characters;</simpara>
</listitem>
<listitem>
<simpara>a <quote><option>?</option></quote> in a pattern stands for exactly one
class name character</simpara>
</listitem>
</itemizedlist>
</para>
</formalpara>
<note><title>Filters work "across directories"</title>
<simpara>You should not think of coverage filters as applying at the
<emphasis>file</emphasis> level. Instead, think of them as applying
at the classpath level. Thus, if you exclude
<quote><option>*Test*</option></quote>, for example, it will have
effect on all application classes that are subject to
instrumentation, no matter from how many classpath directories
and/or <emphasis>.jar</emphasis>s they come.</simpara>
</note>
<formalpara><title>Inclusions and exclusions.</title>
<para>Sometimes all you want is to zoom in to a particular Java
package and don't want to specify a long list of exclusion
patterns (that also needs to be updated each time someone on your
team adds a new Java package to the application). Other times, you do want to
include all of the application's classes but would like to exclude
just a few packages or name patterns (e.g., your testcases or perhaps a
package that is well-tested and can be excluded from coverage
analysis).</para>
</formalpara>
<para>&PROD; coverage filters support all such scenarios and more,
in a reasonably concise and intuitive fashion. Each coverage filter
pattern is either an inclusion or an exclusion pattern:
<itemizedlist>
<listitem>
<simpara>By default, a pattern is an inclusion pattern. This
can also be made explicit by prefixing it with a
<quote><option>+</option></quote> (plus sign).</simpara>
</listitem>
<listitem>
<simpara>A pattern is an exclusion pattern if it is prefixed with a
<quote><option>-</option></quote> (minus sign).</simpara>
</listitem>
</itemizedlist>
</para>
<para>Informally, the way inclusions and exclusions work can be
summarized as follows: a class name is in the
instrumentation set if it is included and not excluded. An <emphasis>empty</emphasis>
list of inclusion patterns implicitly includes everything (i.e., it
is like <quote><option>+*</option></quote>) and an
empty list of exclusion patterns implicitly excludes
nothing. Furthermore, a class name is included if it matches at
least one of the inclusion patterns and not excluded by any
exclusion pattern. It is best to show the formal
matching rule via pseudocode, followed by some examples:
</para>
<formalpara><title>Inclusion/exclusion matching algorithm.</title>
<para>
<synopsis>
if (inclusions is not empty)
{
boolean included = false;
foreach (pattern in inclusions)
{
if (pattern matches classname)
{
included = true;
break;
}
}
if (not included) return classname_is_excluded;
}
if (exclusions is not empty)
{
foreach (pattern in exclusions)
{
if (pattern matches classname) return classname_is_excluded;
}
}
return classname_is_included;
</synopsis>
</para>
</formalpara>
<sect3 id='filtersyntax.ANT'><title>filter syntax: ANT</title>
<para>&PROD; ANT (sub)tasks that can take instrumentation filter
strings either as a <option>filter</option> attribute or as
<option><filter></option> nested elements follow the same
specification syntax:</para>
<formalpara><title><option>filter</option> attribute.</title>
<para>The attribute value is a filter string, which is a list of
inclusion/exclusion patterns, separated with white space and/or commas. Each
inclusion/exclusion pattern is a
<option>*</option>,<option>?</option>-wildcard class name mask, prefixed
with <option>+</option> and <option>-</option> for inclusion and exclusion,
respectively. It is legal to omit a prefix, in which case the inclusion
prefix, <option>+</option>, is implied.</para>
</formalpara>
<simpara>It is also possible to specify a list of
inclusion/exclusion patterns to be loaded from an external file. To do so, you can set
the <option>filter</option> attribute to an <option>@</option>-prefixed file name. The file
should contain a list of inclusion/exclusion patterns, one per line (empty
lines and lines starting with a <quote><option>#</option></quote> are ignored).</simpara>
<formalpara><title><option><filter></option> nested
element.</title>
<para>This nested element can be configured through a
combination of the following attributes:
<informaltable frame='all' tocentry='0'>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' colwidth='1*'/>
<colspec colname='c2' colwidth='4*'/>
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry valign='top'><option>value</option></entry>
<entry>Specifies a list of inclusion/exclusion
patterns, separated with white space and/or commas. Each inclusion/exclusion
pattern is a <option>*</option>,<option>?</option>-wildcard class name mask,
prefixed with <option>+</option> and <option>-</option> for inclusion and
exclusion, respectively. It is legal to omit a prefix, in which case the
inclusion prefix, <option>+</option>, is implied. Note that this attribute
allows you to specify a mixed list of inclusions and exclusions.</entry>
</row>
<row>
<entry valign='top'><option>includes</option></entry>
<entry>Specifies a list of patterns, separated with
white space and/or commas. Each pattern is a
<option>*</option>,<option>?</option>-wildcard class name mask, interpreted
as an inclusion pattern. All explicit <option>+</option>/<option>-</option>
prefixes are ignored.</entry>
</row>
<row>
<entry valign='top'><option>excludes</option></entry>
<entry>Specifies a list of patterns, separated with
white space and/or commas. Each pattern is a
<option>*</option>,<option>?</option>-wildcard class name mask, interpreted
as an exclusion pattern. All explicit <option>+</option>/<option>-</option>
prefixes are ignored.</entry>
</row>
<row>
<entry valign='top'><option>file</option></entry>
<entry>Specifies a list of patterns to be loaded from
a file with a given name. The file should contain a list of
inclusion/exclusion patterns, one per line (empty lines and lines starting
with a <quote><option>#</option></quote> are ignored). Each inclusion/exclusion pattern is a
<option>*</option>,<option>?</option>-wildcard class name mask, prefixed
with <option>+</option> and <option>-</option> for inclusion and exclusion,
respectively. It is legal to omit a prefix, in which case the inclusion
prefix, <option>+</option>, is implied. Note that such a file can contain a
mixed list of inclusions and exclusions.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</formalpara>
<tip>
<title>ANT tip</title>
<simpara>Note that if any of these attributes is set to an empty
string it is ignored. This is convenient for providing team-wide ANT filter
"hooks" that are overridden differently by individual developers
using ANT command line (<option>-Demma.filter=...</option>, etc).</simpara>
</tip>
<bridgehead>Examples</bridgehead>
<para>Note that all these different ways of specifying
instrumentation filters can be used in a combination. The result is a union
of all specified patterns. The following examples all specify the same set
of inclusion/exclusion patterns:</para>
<itemizedlist>
<listitem>
<para>
<programlisting><![CDATA[
<filter includes="com.foo.*" excludes="com.foo.test.*, com.foo.*Test*" />]]></programlisting>
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[
<filter includes="com.foo.*" />
<filter excludes="com.foo.test.*, com.foo.*Test*" />]]></programlisting>
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[
<filter value="+com.foo.*, -com.foo.test.*, -com.foo.*Test*" />]]></programlisting>
</para>
</listitem>
<listitem>
<para>
<programlisting><![CDATA[
<filter excludes="com.foo.*Test*" file="myfilters.txt" />]]></programlisting>
where <filename>myfilters.txt</filename> file contains these lines:
<programlisting><![CDATA[
-com.foo.test.*
+com.foo.*]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect3>
<sect3 id='filtersyntax.cmdline'><title>filter syntax: command line</title>
<para>&PROD; command line tools that can accept instrumentation filter
strings do it via the <option>-ix</option> option. This <glossterm
linkend='repeatable'>repeatable</glossterm> option should be set to a list of
inclusion/exclusion patterns, separated with white space and/or commas. Each
inclusion/exclusion pattern is a
<option>*</option>,<option>?</option>-wildcard class name mask, prefixed
with <option>+</option> and <option>-</option> for inclusion and exclusion,
respectively. It is legal to omit a prefix, in which case the inclusion
prefix, <option>+</option>, is implied.</para>
<simpara>It is also possible to specify a list of
inclusion/exclusion patterns to be loaded from an external file. To do so, you can set
the option value to point to an <option>@</option>-prefixed file name. The file
should contain a list of inclusion/exclusion patterns, one per line (empty
lines and lines starting with a <quote><option>#</option></quote> are ignored).</simpara>
<bridgehead>Examples</bridgehead>
<para>Note that all these different ways of specifying
instrumentation filters can be used in a combination. The result is a union
of all specified patterns. The following examples all specify the same set
of inclusion/exclusion patterns:</para>
<itemizedlist>
<listitem>
<para>
<screen><![CDATA[
>java ]]>∏<![CDATA[ ... -ix +com.foo.*,-com.foo.test.*,-com.foo.*Test* ...]]></screen>
</para>
</listitem>
<listitem>
<para>
<screen><![CDATA[
>java ]]>∏<![CDATA[ ... -ix com.foo.* -ix -com.foo.test.*,-com.foo.*Test* ...]]></screen>
</para>
</listitem>
<listitem>
<para>
<screen><![CDATA[
>java ]]>∏<![CDATA[ ... -ix -com.foo.*Test* -ix @myfilters.txt ...]]></screen>
where <filename>myfilters.txt</filename> file contains these lines:
<programlisting><![CDATA[
-com.foo.test.*
+com.foo.*]]></programlisting>
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<!-- =================== COMMON ====================== -->
<sect1><title>Common ANT task and command line options</title>
<sect2 id='commonoptions.ANT'>
<title>Common ANT task attributes and nested elements</title>
<para>All &PROD; tasks and subtasks have a set of common attributes
and nested elements:</para>
<table tocentry='0' frame='all'><title>Common &PROD; ANT task attributes</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry valign='top'><option>enabled</option></entry>
<entry>If set to <option>false</option>, disables the
corresponding &PROD; ANT task or subtask. This can be used
to effect a simple form of build control flow (default:
<option>true</option>).</entry>
<entry>No (everything is enabled by default)</entry>
</row>
<row id='commonoptions.verbosity.ANT'>
<entry valign='top'><option>verbosity</option></entry>
<entry>Sets the verbosity level for a given task or an
entire <∏> group of tasks. Valid values in the
order of increasing verbosity are:
<itemizedlist>
<listitem><simpara><option>silent</option> (same as
<option>severe</option>): only severe errors are reported;</simpara></listitem>
<listitem><simpara><option>quiet</option> (same as
<option>warning</option>): only warnings and severe
errors are reported;</simpara></listitem>
<listitem><simpara><option>info</option>: default
verbosity level, with &PROD; reporting on
completion of various activities, warnings, and
errors</simpara></listitem>
<listitem><simpara><option>verbose</option>: this
setting makes &PROD; chattier than normal, with extra
progress reporting;</simpara></listitem>
<listitem><simpara><option>trace1</option>, <option>trace2</option>,
<option>trace3</option>: these settings enable internal
tracing (useful mostly for debugging).</simpara></listitem>
</itemizedlist>
(default: <option>info</option>).</entry>
<entry>No (defaults to <option>info</option>)</entry>
</row>
<row id='commonoptions.properties.ANT'>
<entry valign='top'><option>properties</option></entry>
<entry>This option specifies a pathname for an &PROD;
property override file, in the standard
<classname>java.util.Properties</classname> format.
<!-- TODO: doc how ANT resolves relative filenames -->
See <xref linkend='prop-ref'/> for more information on
setting &PROD; properties.</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
<table tocentry='0' frame='all'><title>Common &PROD; ANT task nested elements</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Element</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row id='commonoptions.property.ANT'>
<entry valign='top'><option><property></option></entry>
<entry>This nested element sets a single &PROD; property. It is
the ANT equivalent of <link
linkend='commonoptions.property.cmdline'><option>-D</option></link>
command line option and is provided mostly for internal
testing (&PROD; ANT tasks provide proper attributes and
nested elements for all public tool settings). See <xref linkend='prop-ref'/>
for more information on setting &PROD; properties.</entry>
<entry>No</entry>
</row>
</tbody>
</tgroup>
</table>
<formalpara><title><option><property></option> nested element.</title>
<para>This nested element can be used to set a generic &PROD;
property as a name-value pair using the following attributes:</para>
</formalpara>
<informaltable frame='all' tocentry='0'>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
&TGROUP_ANT3;
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
<entry>Required</entry>
</row>
</thead>
<tbody>
<row>
<entry valign='top'><option>name</option></entry>
<entry>Property name (without
<quote><option>∏.</option></quote> prefix).</entry>
<entry>Yes</entry>
</row>
<row>
<entry valign='top'><option>value</option></entry>
<entry>Property value.</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id='commonoptions.cmdline'>
<title>Common command line options</title>
<titleabbrev id='commonoptions.cmdline.short'>common options</titleabbrev>
<para>All &PROD; command line tools have a set of common options:</para>
<variablelist>
<varlistentry>
<term>
<cmdsynopsis id='commonoptions.properties.cmdline'>
<arg choice='plain'><option>-p, -props, -properties <replaceable>.properties file</replaceable></option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This option specifies a pathname for an &PROD;
property override file, in the standard
<classname>java.util.Properties</classname> format. The
pathname could be either relative (in which case it is resolved relative to the JVM's
current working directory) or absolute. See <xref linkend='prop-ref'/> for more
information on setting &PROD; properties.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis id='commonoptions.property.cmdline'>
<arg
choice='plain'><option>-D<replaceable>name</replaceable>=<replaceable>value</replaceable>,
-D<replaceable>name</replaceable>:<replaceable>value</replaceable>,
-D<replaceable>name</replaceable> <replaceable>value</replaceable>
</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This option sets a single &PROD; property. Note
that this is different from using the JVM
<option>-D</option> option (the
<replaceable>name</replaceable> is not
<quote><option>∏.</option></quote>-prefixed). See <xref linkend='prop-ref'/>
for more information on &PROD; properties.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis id='commonoptions.cmdline.exit'>
<arg choice='plain'><option>-exit</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>To enable tool chaining and integration via <function>main()</function>
entry methods, &PROD; command line tools do not terminate via
<function>java.lang.System.exit()</function> by
default. If desired for shell and makefile integration,
this can be changed by using this option on the command
line. The <emphasis>Diagnostics</emphasis> section on every
tool's reference page details the error codes the tool returns to
the operating system.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis id='commonoptions.cmdline.log'>
<arg choice='plain'><option>-silent</option></arg>
<sbr/>
<arg choice='plain'><option>-quiet</option></arg>
<sbr/>
<arg choice='plain'><option>-verbose</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>These options set &PROD; tool verbosity levels to be
much lower than normal, lower than normal, and above normal,
respectively. These options are shortcuts to setting the
<phrase role='property'><xref
linkend='prop-ref.verbosity.level'/></phrase>
property.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<cmdsynopsis id='commonoptions.cmdline.h'>
<arg choice='plain'><option>-h, -help</option></arg>
</cmdsynopsis>
</term>
<listitem>
<simpara>This option causes &PROD; tools to print their
usage summaries to <classname>System.out</classname>. The
longer form of the option results in slightly more detailed
usage printout.</simpara>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</chapter>
<!-- ================================================================= -->
<chapter id='prop-ref'><title>&PROD; Property Reference</title>
<para>The behavior of &PROD; tools and runtime is influenced by a number of
&PROD; properties (see <xref linkend='prop-ref.tables'/> for the full list). These properties address several needs:
<itemizedlist>
<listitem>
<simpara>It could be tedious or impractical to specify
all individual command line options for
certain aspects of &PROD; behavior (e.g., coverage report
generation properties). A large set of &PROD; property value
overrides can be kept in a file that is referenced with a single
option or from the classpath.</simpara>
</listitem>
<listitem>
<simpara>Certain kinds of instrumented runtimes cannot be
configured easily via command line options (e.g., servlets or Enterprise
Java Beans (<abbrev>EJBs</abbrev>)). Again, other ways of passing
property overrides are need in such cases, such the JVM system options or
classpath resource files.</simpara>
</listitem>
</itemizedlist>
</para>
<sect1>
<title>Specifying &PROD; properties</title>
<!--
property naming convention
cover the case of -out option vs -D...out.file option specified at the same time
usage cases: cmd line (jre/classes), websphere, ANT,
-->
<para>Given an &PROD; <replaceable>property</replaceable> (from
the tables in <xref linkend='prop-ref.tables'/>), it can be specified in several different ways:
<itemizedlist>
<listitem>
<simpara>as a JVM system property named
<option>∏.<replaceable>property</replaceable></option>;</simpara>
</listitem>
<listitem>
<simpara>as a property named
<option>∏.<replaceable>property</replaceable></option>
defined in an external
<classname>java.util.Properties</classname> file;</simpara>
</listitem>
<listitem>
<simpara>as a property named
<option><replaceable>property</replaceable></option>
defined in a <classname>java.util.Properties</classname>
classloader resource;</simpara>
</listitem>
<listitem>
<simpara>as an explicit ANT task <link
linkend="commonoptions.property.ANT"><option><property></option></link> or command
line (<link linkend="commonoptions.property.cmdline"><option>-D</option></link>) property override.</simpara>
</listitem>
</itemizedlist>
The general rule is that when a property is provided at the JVM system
level, its name must be prefixed with
<quote><option>∏.</option></quote> in order to be in &PROD; namespace.
</para>
<bridgehead>Examples</bridgehead>
<para>The following shows different ways of overriding the default
coverage session dump file pathname from ANT or command line. Using
<option>emma.properties</option> or <link
linkend='commonoptions.properties.ANT'><option>properties</option></link>
ANT is convenient when you want to load a large block of &PROD;
property settings without keeping them in your makefile or
<filename>build.xml</filename>:</para>
<itemizedlist>
<listitem>
<para>From ANT:
<programlisting><![CDATA[
<emmajava enabled="${emma.enabled}" libclasspathref="emma.lib"
dumpsessiondata="yes" properties="my.properties"
classname="Main"
classpathref="run.classpath"
/>]]></programlisting>
where file <filename>my.properties</filename> sets
<option>session.out.file</option> to some <replaceable>mydir/myfile</replaceable> value.
</para>
</listitem>
<listitem>
<para>From command line:
<screen><![CDATA[
>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 ...]]></screen>
where file <filename>my.properties</filename> sets
<option>session.out.file</option> to some <replaceable>mydir/myfile</replaceable> value.
</para>
</listitem>
</itemizedlist>
<formalpara id='prop-ref.lookup'><title>&PROD; property lookup order.</title>
<para>Because of multiple ways to specify the same &PROD;
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):
<orderedlist numeration='arabic'>
<listitem>
<simpara>Certain properties like <option>report.txt.out.encoding</option>,
start out with their default values reflecting Java built-in system properties
like <option>file.encoding</option>. Other properties have their
defaults set in &PROD; code.</simpara>
</listitem>
<listitem>
<simpara>A property can be set in an external
<classname>java.util.Properties</classname> file whose
pathname is the value of the JVM system property
<option>∏.properties</option>
(<option>-D∏.properties=<replaceable>filename</replaceable></option>).
&PROD; properties in such a file are <emphasis>not</emphasis>
prefixed with <quote><option>∏.</option></quote>.</simpara>
</listitem>
<listitem>
<simpara>A property can be set at the JVM system property level,
using
<option>-D∏.<replaceable>property</replaceable>=<replaceable>value</replaceable></option>
syntax.</simpara>
</listitem>
<listitem>
<simpara>A property can be set in a classloader resource named
<filename>∏.properties</filename> using the usual
<classname>java.util.Properties</classname> format (<emphasis>without</emphasis> the
<quote><option>∏.</option></quote> 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.</simpara>
</listitem>
<listitem>
<simpara>A property can be set in an external
<classname>java.util.Properties</classname> file whose
pathname is the value of a <link
linkend='commonoptions.properties.ANT'><option>properties</option></link> ANT
task attribute or a <link
linkend='commonoptions.properties.cmdline'><option>-properties</option></link>
command line option. &PROD; properties in such a file are
<emphasis>not</emphasis> prefixed with <quote><option>∏.</option></quote>.</simpara>
</listitem>
<listitem>
<simpara>A property can be set via a <link
linkend='commonoptions.property.ANT'><option>property</option></link>
ANT task nested element
(<option><property name='<replaceable>name</replaceable>' value='<replaceable>value</replaceable>'/></option>)
or a <link
linkend='commonoptions.property.cmdline'><option>-D</option></link>
&PROD; command line option
(<option>-D<replaceable>property</replaceable>=<replaceable>value</replaceable></option>).
(<emphasis>Without</emphasis> the
<quote><option>∏.</option></quote> prefix: don't confuse
this with JVM system properties.) Note
that in the <command><option><report></option></command> task case this mechanism is largely redundant,
because all report generation properties have dedicated ANT task
attributes.</simpara>
</listitem>
</orderedlist>
</para>
</formalpara>
<formalpara><title>Property shortcuts.</title>
<para>In the special case of report generation properties
(<option>report.*</option>) there is one additional complication. Any
property name that follows the
<option>report.<replaceable>name</replaceable></option> patterns
is actually a report property <emphasis>shortcut</emphasis> in the
sense that is applies to all report types (plain text, HTML, XML). For
some aspects of report generation (e.g., <option>report.units</option>) this is very
appropriate, but for others (e.g., <option>report.out.encoding</option>) you are likely to want report
type-specific settings. To do so, you can specify a
<option>report.<replaceable>report_type</replaceable>.<replaceable>name</replaceable></option>
property. For example, <option>report.txt.out.encoding</option> is
more specific than <option>report.out.encoding</option> as far as
the plain-text report generator is concerned. Note that the
<command><option><report></option></command> ANT task makes this more convenient that
the command line case, because it provides convenience override attributes on all
nested <option><txt></option>, <option><html></option>,
etc elements.</para>
</formalpara>
</sect1>
<sect1 id='prop-ref.tables'>
<title>&PROD; property summary</title>
<table id='prop-ref.table.file' frame='all' tocentry='0'><title>&PROD; file
output properties</title>
<tgroup cols='1' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
<tbody>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.coverage.out.file' xreflabel='coverage.out.file'>coverage.out.file</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><filename>coverage.ec</filename></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&PROD; runtime (&PROD;-instrumented classes)</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>In the offline instrumentation mode, setting
this property is currently the only way to override the
pathname of the runtime coverage output file. If the pathname
is not absolute, it is resolved relative to the current
JRE directory (<option>user.dir</option> system property). Any existing
data in the target file is overwritten unless the <option><link linkend='prop-ref.coverage.out.merge'
endterm='prop-ref.coverage.out.merge'/></option> mode is <option>true</option>.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.coverage.out.merge' xreflabel='coverage.out.merge'>coverage.out.merge</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&PROD; runtime (&PROD;-instrumented classes)</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>When runtime coverage data is dumped by
&PROD; runtime, this property specifies whether any existing data in the
target file should be merged into or overwritten.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.metadata.out.file' xreflabel='metadata.out.file'>metadata.out.file</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><filename>coverage.em</filename></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&INSTR;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>For tools that can output class
instrumentation metadata, this
property sets the output file pathname. If the pathname
is not absolute, it is resolved relative to the current
JRE directory (<option>user.dir</option> system property). Any existing
data in the target file is overwritten unless the <option><link linkend='prop-ref.metadata.out.merge'
endterm='prop-ref.metadata.out.merge'/></option> mode is <option>true</option>.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.metadata.out.merge' xreflabel='metadata.out.merge'>metadata.out.merge</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&INSTR;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>For tools that can output class
instrumentation metadata, this
property specifies whether any existing data in the
target file should be merged into or overwritten.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.session.out.file' xreflabel='session.out.file'>session.out.file</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><filename>coverage.es</filename></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &MERGE;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>For tools that can output combined
metadata+coverage (i.e., session) data, this
property sets the output file pathname. If the pathname
is not absolute, it is resolved relative to the current
JRE directory (<option>user.dir</option> system property). Any existing
data in the target file is overwritten unless the <option><link linkend='prop-ref.session.out.merge'
endterm='prop-ref.session.out.merge'/></option> mode is <option>true</option>.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.session.out.merge' xreflabel='session.out.merge'>session.out.merge</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &MERGE;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>For tools that can output combined
metadata+coverage (i.e., session) data, this
property specifies whether any existing data in the
target file should be merged into or overwritten.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table id='prop-ref.table.report' frame='all' tocentry='0'><title>&PROD; report
generation properties</title>
<tgroup cols='1' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
<tbody>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.units' xreflabel='report.units'>report.units</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>instr</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this property
selects either weighted (<option>instr</option>) or
unweighted (<option>count</option>) coverage
metrics. See <xref linkend='tool-ref.reportunits'/> for
more details.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.depth' xreflabel='report.depth'>report.depth</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><para><emphasis><option>report.depth</option></emphasis> is set to
<option>method</option> and overridden for the plain-text
report type:
<itemizedlist>
<listitem><simpara><emphasis><option>report.txt.depth</option></emphasis>: <option>all</option></simpara></listitem>
</itemizedlist></para></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property selects the report depth level covered by the
report. Valid values (in order of increasing level of
detail) are <option>all</option>,
<option>package</option>, <option>source</option>,
<option>class</option>, and <option>method</option>. See
<xref linkend='tool-ref.reportdepth'/> for more details.
</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.columns' xreflabel='report.columns'>report.columns</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><para><emphasis><option>report.columns</option></emphasis> is set
to <option>name,class,method,block,line</option> and
overridden for the plain-text report type:
<itemizedlist>
<listitem><simpara><emphasis><option>report.txt.columns</option></emphasis>: <option>class,method,block,line,name</option></simpara></listitem>
</itemizedlist></para></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property specifies which coverage metrics and in which
left-to-right order to render in the report output (the
XML report is an exception because it is not columnar:
instead, the column order is used for top-to-bottom XML
element rendering). Valid
column ids are the item name and various types of coverage: <option>name</option>,
<option>class</option> (class coverage),
<option>method</option> (method coverage),
<option>block</option> (block coverage), and
<option>line</option> (line coverage). Coverage types that are not available
for a given item type and debug info level are
automatically ignored. It is perfectly legal so use only a
subset of all possible metrics (e.g., reporting both
block and line coverages is somewhat of an overkill).</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.sort' xreflabel='report.sort'>report.sort</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>+block,+name,+method,+class</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property specifies how to sort data by coverage
metrics: which metrics to sort by, sort directions, and
sort order. It should be set to a comma-separated list
of metric ids (<option>name</option>, <option>class</option>, <option>method</option>,
<option>block</option>, and <option>line</option>), with
each metric id prefixed with <quote>+</quote> for ascending or <quote>-</quote> for
descending sort direction. Multiple sorts are applied in the
left-to-right order of the metric ids as specified by
this property. It is perfectly legal to sort only a subset of
all possible metrics/columns.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.metrics' xreflabel='report.metrics'>report.metrics</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>method:70,block:80,line:80,class:100</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property specifies how to highlight data that fails
minimum coverage requirements (only applies to
plain-text and HTML reports). It should be set to a
comma-separated list of metric id-value pairs, with the
value being the minimum required coverage percentage
(separated by a colon). Metrics ids are <option>name</option>, <option>class</option>, <option>method</option>,
<option>block</option>, and <option>line</option>. It is not necessary to specify
the required percentage for every metric used in a given
report.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.out.file' xreflabel='report.out.file'>report.out.file</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><para><emphasis><option>report.out.file</option></emphasis> is not
set and is instead overridden for all report types:
<itemizedlist>
<listitem><simpara><emphasis><option>report.txt.out.file</option></emphasis>: <option>coverage.txt</option></simpara></listitem>
<listitem><simpara><emphasis><option>report.html.out.file</option></emphasis>: <option>coverage/index.html</option></simpara></listitem>
<listitem><simpara><emphasis><option>report.xml.out.file</option></emphasis>: <option>coverage.xml</option></simpara></listitem>
</itemizedlist></para></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property can be used to override the default locations
for the output files. When a relative pathname is
specified, it is resolved relative to the current
JRE directory (<option>user.dir</option> system
property). Note that the HTML report generator creates
secondary HTML files beyond the report home page
file. These files will be put in a subdirectory that is
a sibling of the home page file and it thus makes
sense to have at least one subdirectory level specified for
<option>report.html.out.file</option> (as is the case
with the default value). &PROD; will create any
intermediate output directories as needed. Output files are
always overwritten.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.report.out.encoding' xreflabel='report.out.encoding'>report.out.encoding</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><para><emphasis><option>report.out.encoding</option></emphasis>
defaults to the JRE <option>file.encoding</option>
system property and is overridden for the HTML and XML report types:
<itemizedlist>
<listitem><simpara><emphasis><option>report.html.out.encoding</option></emphasis>: <option>ISO-8859-1</option></simpara></listitem>
<listitem><simpara><emphasis><option>report.xml.out.encoding</option></emphasis>: <option>UTF-8</option></simpara></listitem>
</itemizedlist></para></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &REPORT;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>During coverage report generation, this
property can be set to customize the character encoding
used for the output files. Default values provided by &PROD; should
be adequate in most situations.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table id='prop-ref.table.instr' frame='all' tocentry='0'><title>&PROD; instrumentation properties</title>
<tgroup cols='1' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
<tbody>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.instr.do_suid_compensation' xreflabel='instr.do_suid.compensation'>instr.do_suid_compensation</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &INSTR;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>Because the bytecode instrumentor used by
&PROD; needs to synthesize a static class initializer
when there is none already and because class initializers are
considered for serialization UID calculations by the
default SUID algorithm, &PROD; will add a compensating
<classname>serialVersionUID</classname> field to the
instrumented class if this property set to
<option>true</option>. This is useful for running
applications and tests when Java classes are (de)serialized
from previously saved content or across client-server
connections when not all JVMs are running instrumented
classes. This property can be set to
<option>false</option> to slightly speed up &PROD;
processing if such compensation is not needed (e.g.,
when no serialization is used).</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.instr.exclude_synthetic_methods' xreflabel='instr.exclude_synthetic_methods'>instr.exclude_synthetic_methods</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &INSTR;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>Depending on the compiler used, the
original application classes can contain any number of
"synthetic" methods that implement certain Java language
features (class literals, inner class accessors, etc)
through bytecode that has no representation in the
original sources. In most cases, excluding these methods
from instrumentation and coverage reporting is the
correct thing to do. This is the default &PROD; behavior.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.instr.exclude_bridge_methods' xreflabel='instr.exclude_bridge_methods'>instr.exclude_bridge_methods</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>true</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>&RUN;, &INSTR;</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>J2SE 1.5 compilers introduce a new kind
of "synthetic" methods used for mapping new features
like generics to the existing class format. These
methods do not have a source code representation. In most
cases, excluding these methods from instrumentation and coverage reporting is the
correct thing to do. This is the default &PROD; behavior.</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<table id='prop-ref.table.verbosity' frame='all' tocentry='0'><title>&PROD; logging properties</title>
<tgroup cols='1' align='left' colsep='1' rowsep='1'>
<colspec colname='c1' />
<tbody>
<row>
<entry>
<variablelist>&PROPREF_FO;
<varlistentry><term>Property:</term>
<listitem><simpara><emphasis><option
id='prop-ref.verbosity.level' xreflabel='verbosity.level'>verbosity.level</option></emphasis></simpara></listitem>
</varlistentry>
<varlistentry><term>Default:</term>
<listitem><simpara><option>info</option></simpara></listitem>
</varlistentry>
<varlistentry><term>Tools affected:</term>
<listitem><simpara>all tools, including &PROD; runtime (&PROD;-instrumented classes)</simpara></listitem>
</varlistentry>
<varlistentry><term>Description:</term>
<listitem><para>This property sets the verbosity of
&PROD; logging. Valid values are (in the order of
increasing verbosity):
<itemizedlist>
<listitem><simpara><option>silent</option> (same as
<option>severe</option>): only severe errors are reported;</simpara></listitem>
<listitem><simpara><option>quiet</option> (same as
<option>warning</option>): only warnings and severe
errors are reported;</simpara></listitem>
<listitem><simpara><option>info</option>: default
verbosity level, with &PROD; reporting on
completion of various activities, warnings, and errors
</simpara></listitem>
<listitem><simpara><option>verbose</option>: this
setting makes &PROD; chattier than normal, with extra
progress reporting;</simpara></listitem>
<listitem><simpara><option>trace1</option>, <option>trace2</option>,
<option>trace3</option>: these settings enable internal
tracing (useful mostly for debugging).</simpara></listitem>
</itemizedlist>
</para></listitem>
</varlistentry>
</variablelist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</chapter>
<!-- ================================================================= -->
<glossary>
<glossentry id='coverage.line'>
<glossterm>line coverage</glossterm>
<glossdef>
<para>Coverage metric whereby every source line is given a coverage
percentage. &PROD; derives line coverage from basic block
coverage. The details of this computation are published elsewhere.</para>
</glossdef>
</glossentry>
<glossentry id='instr.run'>
<glossterm>instrumentation run</glossterm>
<glossdef>
<para>A single invocation of the <command>instr</command> command
line tool or the <command><instr></command> ANT task.</para>
</glossdef>
</glossentry>
<glossentry id='instr.set'>
<glossterm>instrumentation set</glossterm>
<glossdef>
<para>A set of Java <filename>.class</filename> definitions that are
included in an &PROD; report. Note that this set is usually smaller
than any set of files input into an &PROD; tool because not all input
classes are executable and users can do additional filtering.</para>
</glossdef>
</glossentry>
<glossentry id='mdata'>
<glossterm>class metadata</glossterm>
<glossdef>
<para>A set of binary Java class descriptors that record
details of class structure like the number of methods in a class,
their name and basic block structure. As long as the original
classes are not recompiled, the same metadata can be used for any
number of coverage profiling runs. See also <xref linkend="tool-ref.instr.mdata"/>.</para>
</glossdef>
</glossentry>
<glossentry id='rdata'>
<glossterm>coverage runtime data</glossterm>
<glossdef>
<para>A set of binary Java class descriptors that reflect a
particular coverage profiling run (which method and basic blocks
were hit for which class, etc). As long as they correspond to
the same metadata, several such data sets can be merged together.</para>
</glossdef>
</glossentry>
<glossentry id='sdata'>
<glossterm>coverage session data</glossterm>
<glossdef>
<para>A combination of <glossterm
linkend='mdata'>metadata</glossterm> and <glossterm
linkend='mdata'>runtime coverage data</glossterm>, usually obtained
during an on-the-fly application session or as a result of using
&MERGE; processor. When this combination is consistent (the runtime
data corresponds to the classes in the metadata), it is
sufficient for a coverage report to be produced.</para>
</glossdef>
</glossentry>
<glossentry id='mergeable'>
<glossterm>mergeable option</glossterm>
<glosssee otherterm='repeatable'/>
</glossentry>
<glossentry id='repeatable'>
<glossterm>repeatable option</glossterm>
<glossdef>
<para>An ANT task nested element or a command line
option that could be used multiple times within a given tool
invocation, with the resulting property value being
a union of all provided inputs (with duplicates removed, if that
makes sense for a given property). In most cases, an individual
input value can also be a comma-separated list of values.</para>
</glossdef>
</glossentry>
</glossary>
</book>
<!--
<screen><![CDATA[
]]></screen>
]]><![CDATA[
-->