Run Emma instrumentation of Java classes.
| Task package: | com.vladium.emma |
| Java package: | |api:package-summary:?linkClass=| |
| Category: | Analyzing tasks |
| Since: | 0.5 |
| EntityFS-aware? | No* |
| Implements: | ActionTaskFactory GeneratorTaskFactory ProcessTaskFactory |
Description:
Run Emma
instrumentation of a set of compiled Java classes. The classes are instrumented
by running Emma's emma command in a forked process.
For more information on the different properties, see the Emma Reference Manual.
When running Emma-instrumented classes, use the EmmaExternalJavaTaskDecorator to enable Emma coverage analysis.
The following strategy is used for searching for the java
command to use:
- Use a Java executable suggested by an ExtJavaTaskDecorator, if any
- Use the
javaExecutableproperty, if set - Use the file
bin/java[.exe]relative to thejavaHomeproperty, if set - Use the file
bin/java[.exe]relative to theJAVA_HOMEenvironment variable, if set - Search for
java[.exe]in the paths listed in thePATHenvironment variable
Required properties
Properties
| assertions | top |
Are assertions enabled? More fine-grained assertion settings can be set by setting JVM options.
- Setter method:
setAssertions(boolean b)
parameters:b– Should assertions be enabled?- Default value:
false(assertions are not enabled).- See also:
- jvmOptions
| coverageFilters | top |
A list of coverage filters, as described in the Emma Reference Manual
- Setter method:
addCoverageFilter(String s)Add one coverage filter.parameters:s– The filter.- Setter method:
addCoverageFilters(Collection<String> c)Add a collection of coverage filters.parameters:c– The collection.
| decorators | top |
A list of ExtJavaTaskDecorator:s. Decorators are used to configure the program to run.
- Setter method:
addDecorator(ExtJavaTaskDecorator d)Add a decorator to the end of the list.parameters:d– A Java task decorator- Setter method:
addDecorators(Collection<? extends ExtJavaTaskDecorator> c)Add a collection of decorators. The decorators are added to the list in the order that they are returned from the collection.parameters:c– A collection of decorators.
| javaExecutable | top |
The path to the java[.exe] command.
Decorators may also set the Java executable to use. In
that case, that setting take precedence.
- Setter method:
setJavaExecutable(Object o)
parameters:o– The path to thejava[.exe]command.
Interpreted byArgumentInterpreter.getFile(java.lang.Object).- Default value:
- The Java executable to use is, in this order of precedence:
- A Java executable set by any of the
decorators. - This property.
- A Java executable found in the catalog referenced by the
javaHomeproperty, if set. - A Java executable found in the catalog referenced by the
JAVA_HOMEenvironment variable, if set. - A Java executable found in the directories referenced by the
PATHenvironment variable.
- A Java executable set by any of the
- See also:
- javaHome
| javaHome | top |
The location of the Java Runtime Environment or Java Development Kit to use
- Setter method:
setJavaHome(Object o)
parameters:- See also:
- javaExecutable
| javaVMType | top |
The Java virtual machine type to use (client or server).
- Setter method:
setJavaVMType(JavaVMType t)
parameters:t– The virtual machine type:JavaVMType.CLIENTJavaVMType.SERVER
- Default value:
- The JRE:s default virtual machine type, probably client.
| jvmOptions | top |
Options for the java command. Options are
arguments to java given before the class to run, see the JDK
documentation on java.
- Setter method:
addJvmOption(String s)
parameters:s– Add an option- Setter method:
addJvmOptions(Collection<String> c)
parameters:c– Add a collection of options. The options are added in the order that they are returned from the collection.
| logFooter | top |
The message that is logged to info level
after the task has been successfully run.
- Setter method:
setLogFooter(String s)
parameters:s– The footer message.- Default value:
- Empty (no footer message is logged.)
- See also:
- logHeader
| logHeader | top |
The message that is logged to info level
before the task is run.
- Setter method:
setLogHeader(String s)
parameters:s– The header message.- Default value:
- A task class specific message.
- See also:
- logFooter
| merge | top |
Should the metadata be merged into the target file?
- Setter method:
setMerge(boolean b)
parameters:b– Should metadata be merged?- Default value:
false(metadata is not merged).- See also:
- metadataFile
| metadataFile (required) | top |
The location of the file to store metadata in. If this is
set to an existing directory, a file (coverage.em?) will be created
there. If this is set to an existing file, and merge is set
to true, metadata will be merged into that file.
- Setter method:
setMetadataFile(Object o)
parameters:o– The location of the metadata file. This can be an existing directory, an existing file or a future file.
Interpreted byArgumentInterpreter.getFile(java.lang.Object).- Default value:
- Store metadata in the file
coverage.emin the current directory (the directory of the Schmant script). - See also:
- merge
| outmode | top |
The output mode for the instrumentation command.
- Setter method:
setOutmode(EmmaInstrumentationOutmode m)
parameters:m– The output mode.- Default value:
- EmmaInstrumentationOutmode.COPY
| overwriteStrategy | top |
The overwrite strategy decides how the task will react if there already is an entity (file or directory) in a location where it wants to create a new entity.
If the strategy is to not overwrite existing entities, the task will fail when it cannot create the entities that it wants to create.
Non-empty directories are never overwritten, regardless of the chosen strategy.
- Setter method:
setOverwrite(boolean b)Setting this to a value ofparameters:truemeans that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.b– Should an existing entity be overwritten?- Setter method:
setOverwriteStrategy(OverwriteStrategy strat)Set the overwrite strategy.parameters:strat– The overwrite strategy.- Default value:
- DontOverwriteAndThrowException
- See also:
- target
| reportLevel | top |
This property is used to change the Report level for all task created by this task factory. The report level is changed for the thread running the task when the it is run, and is restored to its previous level when the it is done.
- Setter method:
setReportLevel(Level l)Set the report levelparameters:l– The new report level.
| sources (required) | top |
A list of root directories for the directory hierarchies where the class files to instrument are.
Note: The class files, not the Java source files.
- Setter method:
addSource(Object o)Add one directory.parameters:- Setter method:
addSources(Collection<?> o)Add a collection of directories.parameters:- Setter method:
clearSources()Clear the list of source directories.- Setter method:
setSource(Object o)Set one directory, discarding previously set directories.parameters:- Setter method:
setSources(Collection<?> o)Set a collection of source directories, discarding previously set sources.parameters:
| target (semi-required) | top |
The root of the target directory hierarchy for storing instrumented classes.
- Setter method:
setTarget(Object o)
parameters:- See also:
- overwriteStrategy
| traceLogging | top |
If trace logging is enabled for a task, it reports its configuration before it is run.
Trace logging may also be enabled globally for all tasks by calling TraceMode.setTraceMode(boolean).
- Setter method:
setTraceLogging(boolean b)Enable or disable trace logging.parameters:b– Enable trace logging?
Examples
See also this JUnit 4 example.Example 1
Run Emma instrumentation of the classes in
bin (compiled from source files in src) and put the
instrumented classes in bin_instr and
the metadata file in the temporary files directory tmpDir. Run
a program that is analyzed for code coverage and generate text and HTML
reports.
JavaScript
Example 2
Run Emma instrumentation of the classes in
bin (compiled from source files in src) and put the
instrumented classes in bin_instr and
the metadata file in the temporary files directory tmpDir. Run
two programs that are analyzed for code coverage. Merge the data from the two
runs and generate a text report. Note: merging data files is perhaps most
useful for hundreds of data files. In this example, the two data files could as
well have been fed directly into the report task.
JavaScript
* That a task is not EntityFS-aware means that it is not aware of DirectoryView filters (it uses them as plain Directory:s) and also that it usually requires that the entities it takes as arguments are in a File-based file file system. (That they are ECFileResolvable.) A non File-resolvable entity can be made so by using the SchmantFileSystems.makeFileResolvable(org.entityfs.EFile) method.