001package Torello.JavaDoc.SyntaxHiLite;
002
003import java.util.TreeSet;
004import java.io.File;
005
006/**
007 * A Java Interface for caching-system classes that allows a Hi-Liter Tool to efficiently bypass
008 * calls to the server if-and-when an exact-copy of the hilited source-code already exists inside
009 * the cache.
010 */
011public interface HiLiteCache
012{
013    /**
014     * Inform the user how much space (in bytes) is used by this {@code Cache}.
015     * @return The number of bytes being used on the file-system by this {@code Cache}.
016     */
017    public long totalSize();
018
019    /**
020     * Count how many files and directories are contained in this {@code Cache}.
021     * @return The total number of files and sub-directories in the {@code Cache} directory.
022     */
023    public int totalNumber();
024
025    /**
026     * This will save the hash-code {@code TreeSet<Integer>} to disk.  The <B>Master Hash-Code
027     * List</B> just keeps a record of the hashcodes of every {@code String} that was hilited
028     * by the Hiliter <I>(and therefore saved inside the Cache).</I>  This method will save
029     * that Java {@code TreeSet} of Hash-Codes to disk.
030     *
031     * @throws CacheError This {@code Error} will throw if there is a problem writing the
032     * master cache-hash to disk.  The chain-cause {@code Throwable} should be visible, and is
033     * included as the {@code Throwable.getCause()}
034     */
035    public void persistMasterHashToDisk() throws CacheError;
036
037    /**
038     * Retrieves a previously highlighted source code {@code String} from the cache if it exists.
039     * If a Cache-Miss has occurred, then this method shall return null.
040     * 
041     * @param sourceCodeAsString    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_SRC_ASSTR>
042     * @param codeTypeParam         <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_CODE_TP>
043     * @param includeLineNumbers    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_INC_LINEN>
044     * @param styleNum              <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_STYLE_N>
045     * @return                      <EMBED CLASS='external-html' DATA-FILE-ID=HLC_GET_RET>
046     */
047    public String get(
048        final String    sourceCodeAsString,
049        final String    codeTypeParam,
050        final boolean   includeLineNumbers,
051        final byte      styleNum
052    );
053
054    /**
055     * Store a newly highlighted source code {@code String} into the cache for future retrieval.
056     * @param sourceCodeAsString    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_SRC_ASSTR>
057     * @param codeTypeParam         <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_CODE_TP>
058     * @param includeLineNumbers    <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_INC_LINEN>
059     * @param styleNum              <EMBED CLASS='external-html' DATA-FILE-ID=HLC_PARAM_STYLE_N>
060     */
061    public void checkIn(
062        final String    sourceCodeAsString,
063        final String    hilitedCodeAsString, 
064        final String    codeTypeParam,
065        final boolean   includeLineNumbers,
066        final byte      styleNum
067    );
068}