= Managing Roll Files Directly
Per Minborg
:toc: macro
:toclevels: 3
:css-signature: demo
:toc-placement: macro
:icons: font

toc::[]

This document describes how roll files can be managed directly via Java. One example of direct management would be to remove old unused roll files.

== Chronicle FileUtil class

The `FileUtil` class provides useful methods when managing queue files directly and is
link:../src/main/java/net/openhft/chronicle/queue/util/FileUtil.java[located here].

=== Determining if a file has a roll file suffix

The method `FileUtil::hasQueueSuffix` can be used to determine if a file has a roll file suffix (i.e. ".cq4"):

[source,java]
----
if (FileUtil.hasQueueSuffix(file)) {
    doStuffWithTheRollFile(file);
}
----

=== Determining the state of a file

The method `FileUtil::state` can be used to determine the current state of a file:

[source,java]
----
switch (FileUtil.state(file)) {
    case CLOSED: {
        processClosed(file);
        break;
    }
    case OPEN: {
        processOpen(file);
        break;
    }
    case NON_EXISTENT: {
        processNonExistent(file);
        break;
    }
    case UNDETERMINED: {
        processUndetermined(file);
        break;
    }
}
----

NOTE: The method above is only supported on Linux/BSD systems and not Windows.

=== Removable roll files

After some time, there might be lingering queue files that are no longer used. Identifying these files is non-trivial as there might be tailers that are still on older roll files.

For example, appenders may be on roll file 10, tailer A on file 3 and tailer B on file 5. In this case, it is only safe to remove the rolls 0, 1 and 2. In particular, roll 4 must not be removed or else tailer A will eventually fail.

The removal candidates can be identified by invoking the `FileUtil::removableRollFileCandidates` method as described hereunder:

[source,java]
----
List<File> candidates = FileUtil.removableRollFileCandidates(dir).collect(toList());
----

This will provide a new List with all candidates in the provided `dir`.

NOTE: It always the ultimate decision of the user code to actually decide if a candidate should be deleted or not.

NOTE: The method above is only supported on Linux/BSD systems and not Windows.

If the used code intends to remove all candidates unconditionally, the following snippet can be used:

[source,java]
----
for (File file : removableFileCandidates(baseDir).collect(Collectors.toList())) {
    if (!file.delete()) {
        break;
    }
}
----

=== Removable roll files via the command line

It is possible to obtain removable roll file candidates directly from the command line:

[source, sh]
----
mvn exec:java -Dexec.mainClass="net.openhft.chronicle.queue.internal.main.InternalRemovableRollFileCandidatesMain" -Dexec.classScope=compile -Dexec.args="my_queue_dir"
----

This will produce a list of removable roll file candidates listed per line.

<<../README.adoc#,Back to Chronicle Queue>>
