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

import de.intevation.artifacts.CallContext;

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

import java.io.Serializable;

import java.util.Collection;
import java.util.Map;

import org.w3c.dom.Document;
import org.w3c.dom.Node;

/**
 * This interface describes the basic method a concrete state class needs to
 * implement.
 *
 * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
 * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
 * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
 */
public interface State extends Serializable {

    /**
     * Setup the state.
     *
     * @param configuration State configuration.
     */
    public void setup(Node configuration);

    /**
     * Return the id of the state.
     *
     * @return the id.
     */
    public String getID();

    /**
     * Return the description of the state.
     *
     * @return the description of the state.
     */
    public String getDescription();

    /**
     * This method is called when an artifacts retrieves a describe request. It
     * creates the user interface description of the current state.
     *
     * @param document Describe doucment.
     * @param rootNode Parent node for all new xml elements.
     * @param context The CallContext.
     * @param uuid The uuid of an artifact.
     */
    public void describe(
        Document    document,
        Node        rootNode,
        CallContext context,
        String      uuid
    );

    /**
     * This method is used to insert new data into this state. Concrete
     * subclasses should valide the input before saving it.
     *
     * @param context The CallContext.
     * @param inputData New InputData items.
     * @param uuid The uuid of an artifact.
     * @return a document with an error or sucess message.
     * @throws StateException
     */
    public Document feed(
        CallContext context, Collection<InputData> inputData, String uuid)
    throws StateException;

    /**
     * Set the previous state.
     *
     * @param state The previous state.
     */
    public void setParent(State state);

    /**
     * Returns the previous state.
     *
     * @return the previous state.
     */
    public State getParent();

    /**
     * Retrieve a collection of required input values.
     *
     * @return required input values.
     */
    public Collection<InputValue> getRequiredInputValues();

    /**
     * Retrieves a map with InputData items.
     *
     * @return a map with InputData items.
     */
    public Map<String, InputData> inputData();

    /**
     * Use this method to feed a state with some data.
     *
     * @param inputData InputData collection.
     * @param uuid UUID of an artifact.
     * @throws StateException
     */
    public void putInputData(Collection<InputData> inputData, String uuid)
    throws StateException;

    /**
     * Retrieves a collection with the InputData stored in this state.
     *
     * @return An InputData collection.
     * @throws StateException
     */
    public Collection<InputData> getInputData() throws StateException;

    /**
     * This method is called to advance to a next or previous state.
     *
     * @param uuid The uuid of an artifact.
     * @param context The CallContext object.
     * @throws StateException
     */
    public void advance(String uuid, CallContext context)
    throws StateException;

    /**
     * This method is called when the state is created.
     *
     * @param uuid The uuid of an artifact.
     * @param context The CallContext object.
     * @throws StateException
     */
    public void initialize(String uuid, CallContext context)
    throws StateException;

    /**
     * This method can be used to reset the state.
     *
     * @param uuid The uuid of an artifact.
     */
    public void reset(String uuid);

    /**
     * This method is called when the lifetime of an artifact ends or if the
     * user decides to step back to a previous state.
     *
     * @param globalContext The CallContext.
     */
    public void endOfLife(Object globalContext);

    /**
     * This method is used to put some InputData objects into an artifact before
     * the parameterization begins.
     *
     * @param preSettings
     */
    public void setPreSettings(Map<String,InputData> preSettings);

    /**
     * This method retrieves a map with InputData objects which have been
     * inserted into this state before the parameterization has started. The key
     * used to store the objects is the name of the state.
     *
     * @return map with InputData objects.
     */
    public Map<String,InputData> getPreSettings();

    /**
     * Method to remove the data stored at a state which should not be
     * serialized while an artifact is exported.
     *
     * @param context The CallContext
     */
    public void cleanup(Object context);
}
// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf-8 :