clover2:instrumentInternal

Full name:

com.atlassian.maven.plugins:maven-clover2-plugin:3.0.0-m4r3:instrumentInternal

Description:

Instrument source roots.

Note 1: Do not call this MOJO directly. It is meant to be called in a custom forked lifecycle by the other Clover plugin MOJOs.

Note 2: We bind this mojo to the "validate" phase so that it executes prior to any other mojos

Attributes:

  • Requires a Maven 2.0 project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • Binds by default to the lifecycle phase: validate.

Required Parameters

Name Type Since Description
cloverMergeDatabase String - The location of the merged clover database to create when running a report in a multimodule build. Default value is: ${project.build.directory}/clover/cloverMerge.db.
cloverOutputDirectory String - The directory where the Clover plugin will put all the files it generates during the build process. For example the Clover plugin will put instrumented sources somewhere inside this directory. Default value is: ${project.build.directory}/clover.
localRepository ArtifactRepository - Local maven repository.
pluginArtifacts List - List of all artifacts for this Clover plugin provided by Maven. This is used internally to get a handle on the Clover JAR artifact.

Note: This is passed by Maven and must not be configured by the user.
project MavenProject - The Maven project instance for the executing project.

Note: This is passed by Maven and must not be configured by the user.

Optional Parameters

Name Type Since Description
cloverDatabase String - The location of the Clover database.
cloveredArtifactExpiryInMillis long - The difference (in milliseconds) that a -clover classified artifact can have to a non-clover classified artifact. If the -clover classified artifact is more than cloveredArtifactExpiryInMillis older than the non-clover classified artifact, then the non-classified artifact will be used. This setting defaults to 2000. Default value is: 2000.
copyExcludedFiles boolean - If set, then the maven-clover2-plugin will not copy files that were excluded, across to the target/clover directory. This is useful if the build is also using plugins such as the maven-gwt-plugin, that scans for resources, and skips a step if none are found. Otherwise, setting this to false could well cause build failures. Default value is: true.
debug boolean - If you wish to enable debug level logging in just the Clover plugin, set this to true. This is useful for integrating Clover into the build Default value is: false.
distributedCoverage DistributedCoverage - The configuration for distributed coverage collection by Clover. If present, default values will be used and coverage will be collected across JVMs. Optional nested elements (and their defaults) of distributedCoverage are:
  • host - the host name of the JVM running the tests. default: localhost
  • port - the port that Clover can bind to in the host JVM. default: 1198
  • numClients - the number of clients expected to attach to the Test JVM. The test JVM will wait until numClients have connected before continuing. default: 0
  • timeout - the amount of time to wait for a response from a remote JVM before shunning it. default: 5000
  • retryPeriod - the amount of time a client should wait between reconnect attempts. default: 1000
encoding String - The character encoding to use when parsing source files.
excludes Set - The list of file to exclude from the instrumentation.
excludesList String - The comma seperated list of file to exclude from the instrumentation.
flushInterval int - When the Clover Flush Policy is set to "interval" or threaded this value is the minimum period between flush operations (in milliseconds). Default value is: 500.
flushPolicy String - The Clover flush policy to use. Valid values are directed, interval and threaded. Default value is: threaded.
includes Set - The list of file to include in the instrumentation. Defaults are **.java which are overwritten if <includes> is set by the user
includesAllSourceRoots boolean - Whether the Clover plugin should instrument all source roots (ie even generated sources) or whether it should only instrument the main source root. Default value is: false.
includesList String - The comma seperated list of files to include in the instrumentation. Defaults are **.java which are overwritten if <includes> is set by the user
includesTestSourceRoots boolean - Whether the Clover plugin should instrument test source roots. Default value is: true.
instrumentation String - The level to instrument to. Valid values are 'method' or 'statement'. Default is 'statement'. Setting this to 'method' greatly reduces the overhead of enabling Clover, however limited or no reporting is available. The current use of setting this to method is for Test Optimization only.
jdk String - Whether the Clover instrumentation should use the Clover jdk14, jdk15 or jdk16 flags to parse sources. Valid values are 1.4, 1.5 and 1.6 .
license String - The full Clover license String to use. If supplied, this certificate will be used over licenseLocation. NB. newline chars must be preserved. A trial Clover license can be generated here.
licenseLocation String - A Clover license file to be used by the plugin. The plugin tries to resolve this parameter first as a resource, then as a URL, and then as a file location on the filesystem. A trial Clover license can be generated here.
methodContexts Map - Specifies the custom method contexts to use for filtering specific methods from Clover reports. e.g. 
<main>public static void main\(String args\[\]\).*</main>
will define the context called 'main' which will match all public static void main methods.
scope String - When creating the clover.jar dependency, what scope to use. This may be one of: compile, test, provided etc. If not specified - provided will be used.
singleCloverDatabase boolean - If true, then a single cloverDatabase will be used for the entire project. This flag will be ignored if a custom cloverDatabase location is specified. Default value is: false.
skip boolean - A flag to indicate not to run clover for this execution. If set to true, Clover will not be run. Default value is: false.
snapshot File - The location to store the clover snapshot file. This file needs to persist between builds to enable Clover's build optimization feature. If not specified, the snapshot will be stored next to the cloverDatabase.
staleMillis int - Sets the granularity in milliseconds of the last modification date for testing whether a source needs reinstrumentation. Default value is: 0.
statementContexts Map - Specifies the custom statement contexts to use for filtering specific statements from Clover reports. e.g. 
<log>^LOG\..*</log>

defines a statement context called "log" which matches all LOG statements.
useCloverClassifier boolean - Whether or not to include the -clover classifier on artifacts. Default value is: true.
useFullyQualifiedJavaLang boolean - Use the fully qualified package name for java.lang.* classes. Default value is: true.
waitForFlush boolean - If true we'll wait 2*flushInterval to ensure coverage data is flushed to the Clover database before running any query on it.

Note: The only use case where you would want to turn this off is if you're running your tests in a separate JVM. In that case the coverage data will be flushed by default upon the JVM shutdown and there would be no need to wait for the data to be flushed. As we can't control whether users want to fork their tests or not, we're offering this parameter to them.

Default value is: true.

Parameter Details

cloverDatabase:

The location of the Clover database.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.cloverDatabase}

cloverMergeDatabase:

The location of the merged clover database to create when running a report in a multimodule build.

  • Type: java.lang.String
  • Required: Yes
  • Expression: ${maven.clover.cloverMergeDatabase}
  • Default: ${project.build.directory}/clover/cloverMerge.db

cloverOutputDirectory:

The directory where the Clover plugin will put all the files it generates during the build process. For example the Clover plugin will put instrumented sources somewhere inside this directory.

  • Type: java.lang.String
  • Required: Yes
  • Default: ${project.build.directory}/clover

cloveredArtifactExpiryInMillis:

The difference (in milliseconds) that a -clover classified artifact can have to a non-clover classified artifact. If the -clover classified artifact is more than cloveredArtifactExpiryInMillis older than the non-clover classified artifact, then the non-classified artifact will be used. This setting defaults to 2000.

  • Type: long
  • Required: No
  • Expression: ${maven.clover.cloveredArtifactExpiryInMillis}
  • Default: 2000

copyExcludedFiles:

If set, then the maven-clover2-plugin will not copy files that were excluded, across to the target/clover directory. This is useful if the build is also using plugins such as the maven-gwt-plugin, that scans for resources, and skips a step if none are found. Otherwise, setting this to false could well cause build failures.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.copyExcludedFiles}
  • Default: true

debug:

If you wish to enable debug level logging in just the Clover plugin, set this to true. This is useful for integrating Clover into the build

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.debug}
  • Default: false

distributedCoverage:

The configuration for distributed coverage collection by Clover. If present, default values will be used and coverage will be collected across JVMs. Optional nested elements (and their defaults) of distributedCoverage are:

  • host - the host name of the JVM running the tests. default: localhost
  • port - the port that Clover can bind to in the host JVM. default: 1198
  • numClients - the number of clients expected to attach to the Test JVM. The test JVM will wait until numClients have connected before continuing. default: 0
  • timeout - the amount of time to wait for a response from a remote JVM before shunning it. default: 5000
  • retryPeriod - the amount of time a client should wait between reconnect attempts. default: 1000

  • Type: com.atlassian.maven.plugin.clover.DistributedCoverage
  • Required: No

encoding:

The character encoding to use when parsing source files.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.encoding}

excludes:

The list of file to exclude from the instrumentation.

  • Type: java.util.Set
  • Required: No

excludesList:

The comma seperated list of file to exclude from the instrumentation.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.excludesList}

flushInterval:

When the Clover Flush Policy is set to "interval" or threaded this value is the minimum period between flush operations (in milliseconds).

  • Type: int
  • Required: No
  • Expression: ${maven.clover.flushInterval}
  • Default: 500

flushPolicy:

The Clover flush policy to use. Valid values are directed, interval and threaded.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.flushPolicy}
  • Default: threaded

includes:

The list of file to include in the instrumentation. Defaults are **.java which are overwritten if <includes> is set by the user

  • Type: java.util.Set
  • Required: No

includesAllSourceRoots:

Whether the Clover plugin should instrument all source roots (ie even generated sources) or whether it should only instrument the main source root.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.includesAllSourceRoots}
  • Default: false

includesList:

The comma seperated list of files to include in the instrumentation. Defaults are **.java which are overwritten if <includes> is set by the user

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.includesList}

includesTestSourceRoots:

Whether the Clover plugin should instrument test source roots.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.includesTestSourceRoots}
  • Default: true

instrumentation:

The level to instrument to. Valid values are 'method' or 'statement'. Default is 'statement'. Setting this to 'method' greatly reduces the overhead of enabling Clover, however limited or no reporting is available. The current use of setting this to method is for Test Optimization only.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.instrumentation}

jdk:

Whether the Clover instrumentation should use the Clover jdk14, jdk15 or jdk16 flags to parse sources. Valid values are 1.4, 1.5 and 1.6 .

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.jdk}

license:

The full Clover license String to use. If supplied, this certificate will be used over licenseLocation. NB. newline chars must be preserved. A trial Clover license can be generated here.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.license}

licenseLocation:

A Clover license file to be used by the plugin. The plugin tries to resolve this parameter first as a resource, then as a URL, and then as a file location on the filesystem. A trial Clover license can be generated here.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.licenseLocation}

localRepository:

Local maven repository.

  • Type: org.apache.maven.artifact.repository.ArtifactRepository
  • Required: Yes
  • Expression: ${localRepository}

methodContexts:

Specifies the custom method contexts to use for filtering specific methods from Clover reports. e.g. 

<main>public static void main\(String args\[\]\).*</main>
will define the context called 'main' which will match all public static void main methods.

  • Type: java.util.Map
  • Required: No

pluginArtifacts:

List of all artifacts for this Clover plugin provided by Maven. This is used internally to get a handle on the Clover JAR artifact.

Note: This is passed by Maven and must not be configured by the user.

  • Type: java.util.List
  • Required: Yes
  • Expression: ${plugin.artifacts}

project:

The Maven project instance for the executing project.

Note: This is passed by Maven and must not be configured by the user.

  • Type: org.apache.maven.project.MavenProject
  • Required: Yes
  • Expression: ${project}

scope:

When creating the clover.jar dependency, what scope to use. This may be one of: compile, test, provided etc. If not specified - provided will be used.

  • Type: java.lang.String
  • Required: No
  • Expression: ${maven.clover.scope}

singleCloverDatabase:

If true, then a single cloverDatabase will be used for the entire project. This flag will be ignored if a custom cloverDatabase location is specified.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.singleCloverDatabase}
  • Default: false

skip:

A flag to indicate not to run clover for this execution. If set to true, Clover will not be run.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.skip}
  • Default: false

snapshot:

The location to store the clover snapshot file. This file needs to persist between builds to enable Clover's build optimization feature. If not specified, the snapshot will be stored next to the cloverDatabase.

  • Type: java.io.File
  • Required: No
  • Expression: ${maven.clover.snapshot}

staleMillis:

Sets the granularity in milliseconds of the last modification date for testing whether a source needs reinstrumentation.

  • Type: int
  • Required: No
  • Expression: ${maven.clover.staleMillis}
  • Default: 0

statementContexts:

Specifies the custom statement contexts to use for filtering specific statements from Clover reports. e.g. 

<log>^LOG\..*</log>

defines a statement context called "log" which matches all LOG statements.

  • Type: java.util.Map
  • Required: No

useCloverClassifier:

Whether or not to include the -clover classifier on artifacts.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.useCloverClassifier}
  • Default: true

useFullyQualifiedJavaLang:

Use the fully qualified package name for java.lang.* classes.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.useFullyQualifiedJavaLang}
  • Default: true

waitForFlush:

If true we'll wait 2*flushInterval to ensure coverage data is flushed to the Clover database before running any query on it.

Note: The only use case where you would want to turn this off is if you're running your tests in a separate JVM. In that case the coverage data will be flushed by default upon the JVM shutdown and there would be no need to wait for the data to be flushed. As we can't control whether users want to fork their tests or not, we're offering this parameter to them.

  • Type: boolean
  • Required: No
  • Expression: ${maven.clover.waitForFlush}
  • Default: true