1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
package Torello.JavaDoc.SyntaxHiLite;

import java.util.TreeSet;
import java.io.File;

/**
 * A Java Interface for caching-system classes that allows a Hi-Liter Tool to efficiently bypass
 * calls to the server if-and-when an exact-copy of the hilited source-code already exists inside
 * the cache.
 */
public interface HiLiteCache
{
    /**
     * Inform the user how much space (in bytes) is used by this {@code Cache}.
     * @return The number of bytes being used on the file-system by this {@code Cache}.
     */
    public long totalSize();

    /**
     * Count how many files and directories are contained in this {@code Cache}.
     * @return The total number of files and sub-directories in the {@code Cache} directory.
     */
    public int totalNumber();

    /**
     * This will save the hash-code {@code TreeSet<Integer>} to disk.  The <B>Master Hash-Code
     * List</B> just keeps a record of the hashcodes of every {@code String} that was hilited
     * by the Hiliter <I>(and therefore saved inside the Cache).</I>  This method will save
     * that Java {@code TreeSet} of Hash-Codes to disk.
     *
     * @throws CacheError This {@code Error} will throw if there is a problem writing the
     * master cache-hash to disk.  The chain-cause {@code Throwable} should be visible, and is
     * included as the {@code Throwable.getCause()}
     */
    public void persistMasterHashToDisk() throws CacheError;

    /**
     * Retrieves a previously highlighted source code {@code String} from the cache if it exists.
     * If a Cache-Miss has occurred, then this method shall return null.
     * 
     * @param sourceCodeAsString    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_SRC_ASSTR>
     * @param codeTypeParam         <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_CODE_TP>
     * @param includeLineNumbers    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_INC_LINEN>
     * @param styleNum              <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_STYLE_N>
     * @return                      <EMBED CLASS='external-html' DATA-FILE-ID=HLC_GET_RET>
     */
    public String get(
        final String    sourceCodeAsString,
        final String    codeTypeParam,
        final boolean   includeLineNumbers,
        final byte      styleNum
    );

    /**
     * Store a newly highlighted source code {@code String} into the cache for future retrieval.
     * @param sourceCodeAsString    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_SRC_ASSTR>
     * @param codeTypeParam         <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_CODE_TP>
     * @param includeLineNumbers    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_INC_LINEN>
     * @param styleNum              <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_STYLE_N>
     */
    public void checkIn(
        final String    sourceCodeAsString,
        final String    hilitedCodeAsString, 
        final String    codeTypeParam,
        final boolean   includeLineNumbers,
        final byte      styleNum
    );
}