At build time, Clover constructs a registry of your source code, and writes it to a file at the location specified in the Clover initstring. When Clover-instrumented code is executed (e.g. by running a suite of unit tests), Clover looks in the same location for this registry file to initialise itself. Clover then records coverage data and writes coverage recording files next to the registry file during execution. See Clover Database Structure for more information.

If you are deploying and running your Clover-instrumented code on different machines, you must provide a way for Clover to find the registry file, and provide a place for Clover to write coverage recording files, otherwise no coverage will be recorded. Clover provides three ways to achieve this:

1. Specify an Initstring that is a globally accessible file path
   The compile-time initstring should be an absolute path to the same filesystem location and be accessible and writable from the build machine and all execution machines. This could be a path on shared drive or filesystem.
2. Specify an Initstring that is a relative path, resolved at runtime
   The compile-time initstring represents a relative path (relative to the CWD of each execution context). To do this you need to specify relative="yes" on the <clover-setup> task.
3. Specify an Initstring at runtime via System properties
   You can override the Clover initstring at runtime via System Properties. Two System properties are supported

   clover.initstring	If not null, the value of this property is treated as an absolute file path to the Clover registry file
   clover.initstring.basedir	If not null (and the clover.initstring System property is not set), the value of this property is used as the base directory for the file specified at compile-time in the initstring to resolve the full path to the Clover registry.
   clover.initstring.prefix	If not null (and the clover.initstring or clover.initstring.basedirSystem properties are not set), the value of this property is prepended to the string value of compile-time specified initstring to resolve the full path to the Clover registry.

   To set one of these properties, you need to pass it on the command line when java is launched, using the -D parameter:

    java -Dclover.initstring=... myapplication.Server

   For application servers, this may involve adding the property to a startup script or batch file.

You must put clover.jar (or the appropriate Clover plugin jar) in the classpath for any JVM that will load classes that have been instrumented by Clover. How you go about this depends on the nature of the application you are testing and the particular environment being deployed to.

In some java environments, such as J2EE containers, applet environments, or applications deployed via Java Webstart, security restrictions are applied to hosted java code that restrict access to various system resources.

To use Clover in these environments, Clover needs to be granted various security permissions for it to function. This requires the addition of a Grant Entry to the security policy file for the Clover jar. For background on the syntax of the policy file, see Default Policy Implementation and Policy File Syntax. For background on setting Java security policies in general, see Permissions in the Java 2 SDK.

Recommended Permissions

Clover requires access to the java system properties for runtime configurations, as well as read write access to areas of the file system to read the clover coverage database and to write coverage information. Clover also uses a shutdown hook to ensure that it flushes any as yet unflushed coverage information to disk when java exits. To support these requirements, the following security permissions are recommended:

grant codeBase "file:/path/to/clover.jar" {
    permission java.util.PropertyPermission "*", "read";
    permission java.io.FilePermission "<<ALL FILES>>", "read, write";
    permission java.lang.RuntimePermission "shutdownHooks";
}