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 files are 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).
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.
Clover has a 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.