Writing your own converter

Writing your own data file reader and/or writer is easy. Simply implement the interface, and register your converter with Java’s ServiceLoader. An example IDataDecoder is given, and may be applied to a custom IDataEncoder as well.

Option 1: Extend AbstractDataDecoder

Your easiest option is simply to extend AbstractDataDecoder. It provides some of the boilerplate functionality necessary to operate a proper decoder.

/**
 * My neat data decoder.
 */
public final class MyDataDecoder extends AbstractDataDecoder {

    /**
     * Returns an iterator for the file.
     *
     * @return An iterator.
     */
    @Override
    protected Iterator<Map<String, Object>> buildIterator() {
        // ... your implementation here.
    }

    /**
     * Retrieve the mimetype which this decoder supports. This must be 
     * unique, and is used to assist in matching decoders to specific file 
     * types.
     *
     * @return The mimetype, as a string.
     */
    @Override
    public String getMimeType() {
        // ... your implementation here.
    }

    /**
     * A disposal method, called before the input stream is disposed of. 
     * Useful if you have custom cleanup logic to execute.
     */
    @Override
    protected void dispose() {
        // Do nothing.
    }
}

Option 1: Implement IDataDecoder

Your second, and more complex option is to implement the IDataDecoder interface directly. It is the more complicated option, however provides you with more detailed control over your implementation.

/**
 * My neat data decoder.
 */
public class MyDataDecoder implements IDataDecoder {

    /**
     * Retrieve the mimetype which this decoder supports. This must be 
     * unique, and is used to assist in matching decoders to specific file 
     * types.
     *
     * @return The mimetype, as a string.
     */
    @Override
    public String getMimeType() {
        // ... your implementation here.
    }

    /**
     * Retrieve the input stream from which the decoder is reading its data.
     *
     * @return The input stream.
     */
    @Override
    public InputStream getInput() {
        // ... your implementation here.
    }

    /**
     * Set the input stream from which the decoder should read its data.
     *
     * @param stream The input stream.
     */
    @Override
    public void setInput(InputStream stream) {
        // ... your implementation here.
    }

    /**
     * Returns an iterator for the file.
     *
     * @return An iterator.
     */
    @Override
    private Iterator<Map<String, Object>> buildIterator() {
        // ... your implementation here.
    }

    /**
     * Close the decoder and disconnect all streams.
     */
    @Override
    public void close() throws IOException {
        // ... your implementation here.
    }

    // ... more implementation here.
}

Register the decoder.

The last step in the process is to register your IDataDecoder with the ServiceLocator. To do this, create a file in your /src/main/resources/META-INF/sevices directory named net.krotscheck.dfr.IDataDecoder, and add the full package and class name of your decoder:

com.yourdomain.MyDataDecoder

From that point forward, your mime type will be automatically registered with the DFR framework.