/*
 * Copyright (c) 2010 by Intevation GmbH
 *
 * This program is free software under the LGPL (>=v2.1)
 * Read the file LGPL.txt coming with the software for details
 * or visit http://www.gnu.org/licenses/ if it does not exist.
 */

package de.intevation.gnv.exports;

import de.intevation.gnv.geobackend.base.Result;

import de.intevation.gnv.state.exception.StateException;

import java.io.IOException;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;

import java.util.Collection;

/**
 * This interface should be implemented by a class whose instances are intended
 * to export a <code>Collection</code> of <code>Result</code>s into a specific
 * format (e.g. CSV or ODV).
 *
 * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
 * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
 */
public interface Export {

    /**
     * This interface provides some methods which describe the format used by an
     * <code>Export</code>.
     */
    public interface Profile {
        /**
         *
         * @param column Column index.
         * @param value A default value.
         * @return A specific column as string.
         */
        String toString(int column, String value);

        /**
         * This method serves information about the character used to separate
         * columns.
         *
         * @return Character used to separate
         */
        char      getSeparator();

        /**
         * This method serves information about the character used as escape
         * character.
         *
         * @return Escape character
         */
        char      getEscapeCharacter();

        /**
         * This method serves informatin about the character used as quote
         * character.
         *
         * @return Quote character
         */
        char      getQuoteCharacter();

        /**
         * This method serves information about the format.
         *
         * @return Format as string.
         */
        String    getType();

        /**
         * This method serves information about the encoding to be used.
         *
         * @return Encoding
         */
        String    getEncoding();

        /**
         * This method returns the header as array.
         *
         * @return Header as string array.
         */
        String [] getHeader();
    }

    /**
     * This interface should be implemeted to collect the required data from
     * <code>Result</code> object.
     */
    public interface DataCollector {

        /**
         * This method serves the required data stored in a <code>Result</code>
         * object.
         *
         * @param result <code>Result</code> object which contains the required
         * data.
         * @return String[] which contains all required data.
         *
         * @throws StateException
         */
        String[] getData(Result result)
        throws StateException;
    }

    /**
     * This method creates an export document specified by {@link Profile} which
     * contains the data stored in <code>result</code> and writes it to
     * <code>outputStream</code>.
     *
     * @param profile Profile used to specify the format of the resulting export
     * document.
     * @param outputStream Resulting export document is written to this
     * OutputStream.
     * @param result Collection which contains the data used to be written into
     * the export document.
     *
     * @throws IOException if an error occured while writing the export document
     * to OutputStream
     * @throws UnsupportedEncodingException if the given encoding is not
     * accepted
     * @throws StateException if <code>result</code> is null
     */
    public void create(
        Profile      profile,
        OutputStream outputStream,
        Collection   result
    )
    throws IOException, UnsupportedEncodingException, StateException;

}
// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf-8 :