/**
 * 
 */
package cz.cuni.mff.peckam.java.origamist.services.interfaces;

import java.io.File;
import java.io.IOException;
import java.net.URI;
import java.net.URL;
import java.util.Set;

import javax.xml.bind.JAXBException;
import javax.xml.bind.MarshalException;

import cz.cuni.mff.peckam.java.origamist.exceptions.UnsupportedDataFormatException;
import cz.cuni.mff.peckam.java.origamist.model.Origami;
import cz.cuni.mff.peckam.java.origamist.utils.ExportFormat;
import cz.cuni.mff.peckam.java.origamist.utils.ExportOptions;

/**
 * A class implementing this interface is able to load an origami model from XML and save
 * cz.cuni.mff.peckam.java.origamist.model.Origami as XML.
 * 
 * @author Martin Pecka
 */
public interface OrigamiHandler
{
    /**
     * Saves the given origami in the given file in XML format according to the latest version of schema.
     * 
     * @param origami The origami to save.
     * @param file The file to save to.
     * 
     * @throws IOException If an IO error occured during saving.
     * @throws MarshalException If JAXB is unable to marshal an element.
     * @throws JAXBException If JAXB initialization failed.
     */
    public void save(Origami origami, File file) throws IOException, MarshalException, JAXBException;

    /**
     * Export the given model to the given format.
     * 
     * @param origami The model to export.
     * @param file The file to save the model to. If multiple files have to be generated, this filename will be used as
     *            a template for generating real filenames.
     * @param format The format of the exported file.
     * 
     * @return The set of files generated by this export action.
     * 
     * @throws IOException If the export or saving fails.
     */
    public Set<File> export(Origami origami, File file, ExportFormat format) throws IOException;

    /**
     * Export the given model to the given format.
     * 
     * @param origami The model to export.
     * @param file The file to save the model to. If multiple files have to be generated, this filename will be used as
     *            a template for generating real filenames.
     * @param format The format of the exported file.
     * @param options The options for the selected format. If <code>null</code>, the default options will be used.
     * 
     * @return The set of files generated by this export action.
     * 
     * @throws IOException If the export or saving fails.
     */
    public Set<File> export(Origami origami, File file, ExportFormat format, ExportOptions options) throws IOException;

    /**
     * Export the given model to the given format.
     * 
     * @param origami The model to export.
     * @param file The file to save the model to. If multiple files have to be generated, this filename will be used as
     *            a template for generating real filenames.
     * @param format The format of the exported file.
     * @param options The options for the selected format. If <code>null</code>, the default options will be used.
     * @param progressCallback The callback to be called every time some part of the export is finished. Mostly this
     *            will either be called once at all, or once for each of the model's step. If <code>null</code>, the
     *            callback is ignored.
     * 
     * @return The set of files generated by this export action.
     * 
     * @throws IOException If the export or saving fails.
     */
    public Set<File> export(Origami origami, File file, ExportFormat format, ExportOptions options,
            Runnable progressCallback) throws IOException;

    /**
     * Load the model saved in path. Always returns the model converted to the newest available schema version.
     * 
     * @param path Path to the model.
     * @param onlyMetadata If true, the contents of the <code>model</code> tag will be skipped. They will be loaded
     *            lazily the first time they will be accessed.
     * @return The model parsed from the given file.
     * 
     * @throws IOException If the file could not be read.
     * @throws UnsupportedDataFormatException If the given file does not contain
     *             a valid model.
     */
    Origami loadModel(URL path, boolean onlyMetadata) throws IOException, UnsupportedDataFormatException;

    /**
     * Load the model saved in path. Always returns the model converted to the newest available schema version.
     * 
     * @param path Path to the model.
     * @param onlyMetadata If true, the contents of the <code>model</code> tag will be skipped. They will be loaded
     *            lazily the first time they will be accessed.
     * @return The model parsed from the given file.
     * 
     * @throws IOException If the file could not be read.
     * @throws UnsupportedDataFormatException If the given file does not contain
     *             a valid model.
     */
    Origami loadModel(URI path, boolean onlyMetadata) throws IOException, UnsupportedDataFormatException;

    /**
     * @return the documentBase
     */
    URL getDocumentBase();

    /**
     * @param documentBase the documentBase to set
     */
    void setDocumentBase(URL documentBase);
}