Coffeewiki¶

Screenshots¶

Take a look at the Coffeearc GUI: Screenshots

A first example how to interface Coffeearc with a command-line compression tool¶

Suppose you have a command-line compression tool “mytool.exe” that accepts some parameters like [options] [in] [out], where [in] is the input file, [out] is the output file and [options] denotes a set of options (e.g. “-c” for compression, “-d” for decompression). While the order and count of the parameters is not important, it is critical, that the compression tool produces exactly the file specified by [out], e.g. a command like

“mytool -c explorer.exe explorer.out”

should compress the file “explorer.exe” and produce the file “explorer.out”. If it appends something to the name or changes the file extension, it won't work. In case the compression succeeds, the tool should return with an exit value of 0 (the same applies for decompression, of course).
To get a tool to work with Coffeearc, you have to create an XML-profile and then copy the tool and the XML-file in the “profiles” directory, which is located in the program directory. Now, a simple working profile for “mytool.exe” would look like this:

<profile name=”mytool” version=”1.0”>
     <gui name="Mode" type="check">
        <option label="Fast" selected=”yes”>
            <replace key="%opt1" with="-f"/>
        </option>
    </gui>
    <encode file="mytool.exe" params="-c %in %out %opt1">
        <decode params="-d %in %out"></decode>
    </encode>
</profile>

The “encode” and “decode” tags define the parameters needed for compression and decompression, respectively. The strings “%in” and “%out” will be automatically replaced by Coffeearc by the right filenames.
Although profiles like this work fine, Coffeearc offers some more features like solid archiving, checksum verfication, multi-threading and other stuff that can be activated by other XML tags. Please read the user guide and/or the information contained in the complete profile example at the end if you want to know more.

Alternative interface: Coffeearc in pipe-mode¶

Configuring the profile for pipes is no more difficult than for the default mode: If one or both of the placeholders for the input- or output files inside the “params” attribute of the encode (or decode) tag are missing, Coffeearc expects the compression tool to

• read data from its process' input stream if the “%in” placeholder is missing (Coffeearc will then write data to the piped process' output stream)
• write data to its process' output stream if the “%out” placeholder is missing (Coffeearc will then read data from the piped process' input stream)

For example, suppose “mytool.exe” could be configured to write compressed data to its process' output stream (instead of a file) by replacing “%out” (i.e. the output filename) by a “:”. Further, reading uncompressed data from the input stream while decompressing could be done by replacing “%in” (i.e. the input filename) by a “:”. Then the “encode” tag of the example profile above would look like this:

<encode file="mytool.exe" params="-c %in : %opt1">
    <decode params="-d : %out"></decode>
</encode>

Since Coffeearc can simultaneously read from and write to a process' in- and output stream, both cases are possible as well:

<encode file="mytool.exe" params="-c : : %opt1">
    <decode params="-d : :"></decode>
</encode>

More platform independence: Using Coffeearc with a Java plugin¶

A Java-based plugin can be created by extending the Coffeearc API. You have to implement two methods whose parameters are buffered input- and output streams. Here is a quick recipe:

1. Download Eclipse (www.eclipse.org).
2. Create a new Java project and add the files “coffeearc.jar” and “libs/truezip-6.jar” to the build path (project properties).
3. Create the encoder class: Extend the class “StreamEncoder” and implement the “compress” method (look at the Coffeearc source if you need more information).
4. For the decoder, do the same with “StreamDecoder” (and the decompress method).
5. Export your project as a JAR file (important: use the manifest file “plugin.mf”).

Here is an example of Coffeearc's "Store-Plugin" implementation. The encoder code is:

public class Encoder extends StreamEncoder
{
    protected void compress(InputStream in, OutputStream out, String[] args, String ext) throws Exception
    {
        int b;
        while ((b=in.read()) != -1) out.write(b);
    }
}

The deocder code is:

public class Decoder extends StreamDecoder
{
    protected void decompress(InputStream in, OutputStream out, String ext) throws Exception
    {
        int b;
        while ((b=in.read()) != -1) out.write(b);
    }
}

Writing a Java plugin is also perfect for creating your own interface to an existing compression tool. There are many possibilities in Java to load native libraries you could use and make your algorithm truly platform-independend. For example, take a look at https://jna.dev.java.net/

Enabling multi-threading¶

Since compression can take time and probably most single-file compression tools don't implement parallelization, the archiver itself is a good place to do just that. The idea is quite simple, Coffeearc just launches more than one compression thread/process at once. However, by default this feature is disabled because not in every case it makes sense to use it and not properly configured, it might do more harm than good. Please be careful on using this feature - read the Coffeearc documentation first!
Generally, switching on multi-threading can simply be done by inserting the

<multithreading/>

tag into the profile. The maxlevel attribute allows you to control the maximum number of threads selectable by the user when creating an archive. For example

<multithreading maxlevel="2"/>

enables Coffeearc to use at most two parallel compression threads (depending on user selection).

Creating GUI elements¶

Creating some useful GUI elements for configuration only requires some lines of XML code. The 'gui' tag creates various GUI elements (radio-buttons, check-boxes or combo-boxes).

<!-- Three radio buttons. If nothing is selected, all placeholders defined will be replaced by empty strings. -->
<gui name="Mode" type="radio">
    <option label="Fast">
        <!-- Selecting this option will replace the placeholders '%opt1' and '%opt3' in
        all encode parameter strings defined later -->
        <replace key="%opt1" with="-f"/>
        <replace key="%opt3" with="-fast"/>
    </option>

    <!-- The attribute 'default="yes"' will preselect this option -->
    <option label="Normal" default="yes">        
        <replace key="%opt1" with="-n"/>
        <replace key="%opt3" with="-normal"/>
    </option>

    <option label="Strong">
        <replace key="%opt1" with="-s"/>
        <replace key="%opt3" with="-strong"/>
    </option>
</gui>

<!-- Two check boxes (one preselected) -->
<gui name="Misc" type="check">
    <option label="Debug">
        <replace key="%opt2" with="-d"/>
    </option>
    <option label="Information" selected="yes">    <!-- The attribute 'selected' is equivalent to 'default'-->
        <replace key="%opt5" with="-i"/>
    </option>
</gui>

<!-- some combo boxes (2nd option preselected) -->
<gui name="Many" type="combo">
    <option label="Another option 1"><replace key="%opt4" with="-a:1"/></option>
    <option label="Another option 2" default="yes"><replace key="%opt4" with="-b:2"/></option>
    <option label="Another option 3"><replace key="%opt4" with="-c:3"/></option>
    <option label="Another option 4"><replace key="%opt4" with="-d:4"/></option>
    <option label="Another option 5"><replace key="%opt4" with="-e:5"/></option>
    <option label="Another option 6"><replace key="%opt4" with="-f:6"/></option>
</gui>

A complete example that covers all features of Coffeearc (profile.xml)¶

If you want to learn more about Coffeearc's features, study the complete example.