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"
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).
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.
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.
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.