/*
 This file is part of the software framework JStatCom, 
 a library for building applications for data based analysis.

 Copyright (C) 2000-2005  Markus Kraetzig

 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as
 published by the Free Software Foundation; either version 2.1 of the
 License, or (at your option) any later version.

 This library is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 USA
 */

package com.jstatcom.io;

import java.io.File;

import com.jstatcom.model.JSCData;
import com.jstatcom.ts.TS;

/**
 * Interface to be implemented by classes that initiate parsing of data files
 * and the creation of datasets. It can be used to import all kinds of datasets,
 * because it does not rely on a distinct dataset class. It only uses the
 * convention that elements of the dataset are stored as JSCData
 * objects and that there exist ImportTypes defining the
 * structure of a dataset.
 * 

 * The implementations of DataHandler should check whether a
 * created dataset is in a consistent state when it can be accessed via
 * getData.
 * 
 * @author Markus Kraetzig 
 */
public interface DataHandler {

    /**
     * Parses file and collects the data as JSCData
     * objects in a SymbolTable. In case of an error this method
     * should throw an exception. The return parameter should only indicate that
     * the import operation was cancelled.
     * 
     * @param file
     *            the file containing the data
     * @return true of import was ok, false if
     *         cancelled
     */
    public boolean importData(File file);

    /**
     * Gets the imported data according to the respective type, which defines
     * the kind of information to retrieve from the imported dataset.
     * 
     * @param type
     *            defines the element of the dataset to get, for example the
     *            start date
     * @return the data stored as JSCData
     */
    public JSCData getData(ImportTypes type);

    /**
     * Exports time series to a file in the format that the respective
     * implementation of this interface handles.
     * 

     * Implementation Note:  

     * Not every handler implementation uses all information contained in a time
     * series. For example, some handlers might not store the variable names,
     * the date, and the description, because this may not be supported by the
     * respective format.
     * 

     * Implementations of this method should throw unchecked exceptions in case
     * of errors, which should be dealt with by the calling objects.
     * 
     * 
     * @param file
     *            the file to store the time series to
     * @param ts
     *            array of time series to export
     * @param description
     *            an optional dataset description that handler implementations
     *            might use
     */
    public void exportTS(File file, TS[] ts, String description);

    /**
     * Exports data to a file in the format that the respective implementation
     * of this interface handles. This method should throw an exception if the
     * type of data is not suppported.
     * 

     * Implementations of this method should throw unchecked exceptions in case
     * of errors, which should be dealt with by the calling objects.
     * 
     * @param file
     *            the file to store the data to
     * @param data
     *            the data object to store, must be supported
     * @param description
     *            an optional description that handler implementations might use
     *  
     */
    public void exportData(File file, JSCData data, String description);

}