Background: The Clover Coverage Database

This section provides background information on the structure, lifecycle and management of the Clover database.

Database structure and lifecycle

The Clover database consists of several files that are constructed at various stages of the instrumentation and coverage recording process. The following table shows the various files created if Clover is initialised with an initstring of "clover.db"

Registry file

Filename: clover.db

Description: The Registry file contains information about all of the classes that have been instrumented by Clover. This file does not contain any actual coverage recording data.

Lifecycle: The Registry file is written during the instrumentation process. If an existing Registry file is found, the existing file is updated. If no Registry file is found, a new Registry file is created. The Registry file is read by Clover-instrumented code when it is executed, and also during report generation or coverage browsing (such as via an IDE plugin or the Swing Viewer).

ContextDef file

Filename: clover.db.ctx

Desription: The ContextDef file contains user-defined context definitions. Note that while this file is in plain text, it is managed by Clover and should not be edited directly by the user.

Lifecycle: The ContextDef file is written prior to Clover instrumentation. The ContextDef file is read during instrumentation, report generation and coverage browsing.

CoverageRecording Files

Filename: clover.dbHHHHHHH_TTTTTTTTTT or clover.dbHHHHHHH_TTTTTTTTTT.1 (where HHHHHHH and TTTTTTTTTT are both hex strings)

Description: CoverageRecording files contain actual coverage data. When running instrumented code, Clover creates one or more Coverage Recorders. Each Coverage Recorder will write one CoverageRecording file. The number of Coverage Recorders created at runtime depends the nature of the application you are Clovering. In general a new Coverage Recorder will be created for each new ClassLoader instance that loads a Clovered class file. The first hex number in the filename (HHHHHHH) is a unique number based on the recording context. The second hex number (TTTTTTTTTT) is the timestamp (ms since epoch) of the creation of the Clover Recorder. CoverageRecording files are named this way to try to minimise the chance of a name clash. While it is theoretically possible that a name clash could occur, in practice the chances are very small.

Lifecycle: CoverageRecording files are written during the execution of Clover-instrumented code. CoverageRecording files are read during report generation or coverage browsing.

Note

Clover 1.3.7 introduced a new failsafe mechanism for writing recording files to disk when using interval-based flush policies. The mechanism alternates between writing to a primary recording file and a secondary recording file. This prevents data loss in the event of abnormal JVM termination. The secondary recording file has the same name as a normal recording file but with .1 appended to its name.

Managing the Clover database

Because the Clover database can consist of many recording files, you might find it easier to create the database in its own directory. This directory can be created at the start of a Clover build, and deleted once coverage reports have been generated from the database.

Although Clover will update an existing database over successive builds, it is in general recommended that the database be deleted after it is used to generate reports, so that a fresh database is created on the next build. Doing this improves the runtime performance of Clover. The <clover-clean> Ant task is provided to allow easy deletion of a Clover database. Note that the IDE Plugins all have a feature to automatically manage the Clover database for you.