/*
 * 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.artifactdatabase.client;

import java.io.IOException;
import java.io.OutputStream;
import java.util.Collection;
import java.util.Locale;

import org.w3c.dom.Document;

import de.intevation.gnv.artifactdatabase.client.exception.ArtifactDatabaseClientException;
import de.intevation.gnv.artifactdatabase.client.exception.ArtifactDatabaseInputException;
import de.intevation.gnv.artifactdatabase.objects.ArtifactDescription;
import de.intevation.gnv.artifactdatabase.objects.ArtifactFactory;
import de.intevation.gnv.artifactdatabase.objects.ArtifactObject;
import de.intevation.gnv.artifactdatabase.objects.ArtifactStatisticsSet;
import de.intevation.gnv.artifactdatabase.objects.InputParameter;
import de.intevation.gnv.artifactdatabase.objects.map.MapService;

/**
 * This interface describes basic methods for the communication between artifact
 * server and this client.
 *
 * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
 * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
 */
public interface ArtifactDatabaseClient {

    public final static String ARTIFACTDATABASE_COUNT_ID = "de.intevation.gnv.artifactdatabase.client.ArtifactDatabase.count";

    public final static String ARTIFACTDATABASE_URL_ID = "de.intevation.gnv.artifactdatabase.client.ArtifactDatabase.url";

    /**
     * Return the Artifactfactories which can be resolved.
     *
     * @return the Artifactfactories which can be resolved.
     * @throws ArtifactDatabaseClientException if a general error occured in the
     * artifact server.
     * @throws ArtifactDatabaseInputException if the input data was valid.
     */
    public Collection<ArtifactObject> getArtifactFactories()
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

    /**
     * Call the create operation of the artifact server and returns a new
     * artifact with the information returned by the artifact server.
     *
     * @param artifactFactory
     * @return the new Artifact
     * @throws ArtifactDatabaseClientException if a general error occured in the
     * artifact server.
     * @throws ArtifactDatabaseInputException if the input data was valid.
     */
    public ArtifactObject createNewArtifact(ArtifactObject artifactFactory)
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

    /**
     * Call the describe operation of the artifact server.
     *
     * @param artifactFactory
     * @param currentArtifact
     * @param includeUI
     * @return the Current Artifact
     * @throws ArtifactDatabaseClientException if a general error occured in the
     * artifact server.
     * @throws ArtifactDatabaseInputException if the input data was valid.
     */
    public ArtifactDescription getCurrentStepDescription(
        ArtifactObject artifactFactory,
        ArtifactObject currentArtifact,
        boolean includeUI)
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

    /**
     *
     * @param artifactFactory
     * @param currentArtifact
     * @param target
     * @param inputParameter
     * @return the artifact description.
     * @throws ArtifactDatabaseClientException if a general error occured in the
     * artifact server.
     * @throws ArtifactDatabaseInputException if the input data was valid.
     */
    public ArtifactDescription doNextStep(
        ArtifactObject artifactFactory,
        ArtifactObject currentArtifact,
        String         target,
        Collection<InputParameter> inputParameter)
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

    /**
     * Calls the advancecommand for the given Artifact at the Artifactdatabase.
     * Stepping to the given target using the given Artifactfactory
     * @param factory the Factory which provide the information about which 
     *                Artifactdatabase has to be called.
     * @param artifact the Artifact which should be moved to the next state.
     * @param target the Id of the next State which should the artifact should 
     *               be moved to.
     * @throws IOException
     * @throws ArtifactDatabaseClientException
     * @throws ArtifactDatabaseInputException
     */
    public void doAdvance(
        ArtifactObject factory,
        ArtifactObject artifact,
        String         target)
    throws IOException, 
           ArtifactDatabaseClientException, 
           ArtifactDatabaseInputException;

    /**
     * @param artifactFactory
     * @param currentArtifact
     * @param inputParameter
     * @throws ArtifactDatabaseClientException if a general error occured in the
     * artifact server.
     * @throws ArtifactDatabaseInputException if the input data was valid.
     */
    public void doFeed(ArtifactObject artifactFactory,
        ArtifactObject currentArtifact,
        Collection<InputParameter> inputParameter)
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

    /**
     * Call the out operation of the artifact server.
     *
     * @param artifactFactory
     * @param currentArtifact
     * @param stream
     * @param targetName
     * @param exportMode
     * @param mimeType
     * @param inputParameter
     * @throws ArtifactDatabaseClientException
     */
    public void doOutput(
        ArtifactObject artifactFactory,
        ArtifactObject currentArtifact,
        OutputStream   stream,
        String         targetName,
        String         exportMode,
        String         mimeType,
        Collection<InputParameter> inputParameter)
    throws ArtifactDatabaseClientException;


    /**
     * Write the current artifact to an xml file.
     *
     * @param artifactFactory
     * @param currentArtifact
     * @param out
     * @throws ArtifactDatabaseClientException
     */
    public void doExport(
        ArtifactObject artifactFactory,
        ArtifactObject currentArtifact,
        OutputStream   out)
    throws ArtifactDatabaseClientException;


    /**
     * Import an artifact from xml file.
     *
     * @param factory
     * @param document
     * @return a status message. If the import was successful, it contains
     * information about the imported artifact, otherwise a failure is
     * contained.
     * @throws ArtifactDatabaseClientException
     * @throws IOException
     */
    public Document doImport(
        ArtifactFactory factory,
        Document        document)
    throws ArtifactDatabaseClientException, IOException;

    /**
     * Publish shapefiles of an artifact as WMS layer.
     *
     * @param factory
     * @param artifact
     * @param inputParameter
     * @return URL to wms service as string
     * @throws ArtifactDatabaseClientException
     * @throws ArtifactDatabaseInputException
     */
    public Document publishWMS(
        ArtifactObject             factory,
        ArtifactObject             artifact,
        Collection<InputParameter> inputParameter
    )throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;


    /**
     * Start statistics calculation.
     *
     * @param artifactFactory
     * @param currentArtifact
     * @return the calculated statistic.
     * @throws ArtifactDatabaseClientException
     */
    public Collection<ArtifactStatisticsSet> calculateStatistics(
        ArtifactObject artifactFactory,
        ArtifactObject currentArtifact)
    throws ArtifactDatabaseClientException;

    /**
     * Set the current locale.
     * @param locale
     */
    public void setLocale(Locale locale);

    /**
     * Get the current locale.
     * @return the current locale.
     */
    public Locale getLocale();

    /**
     * Returns some meta information about the currently selected
     * ArtifactFactory.
     *
     * @param mapServices
     * @param geometry
     * @param srs
     * @return the information.
     * @throws ArtifactDatabaseClientException
     * @throws ArtifactDatabaseInputException
     */
    public Collection<ArtifactObject> getArtifactFactoryMetaInformation(
        Collection<MapService> mapServices,
        String                 geometry,
        String                 srs)
    throws ArtifactDatabaseClientException, ArtifactDatabaseInputException;

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