ingo@1115: /*
ingo@1115:  * Copyright (c) 2010 by Intevation GmbH
ingo@1115:  *
ingo@1115:  * This program is free software under the LGPL (>=v2.1)
ingo@1115:  * Read the file LGPL.txt coming with the software for details
ingo@1115:  * or visit http://www.gnu.org/licenses/ if it does not exist.
ingo@1115:  */
ingo@1115: 
tim@335: package de.intevation.gnv.state;
tim@335: 
sascha@779: import de.intevation.artifacts.CallContext;
sascha@779: 
sascha@779: import de.intevation.gnv.state.exception.StateException;
sascha@779: 
tim@335: import java.io.Serializable;
sascha@779: 
tim@335: import java.util.Collection;
ingo@473: import java.util.Map;
tim@335: 
tim@335: import org.w3c.dom.Document;
tim@335: import org.w3c.dom.Node;
tim@335: 
tim@335: /**
ingo@796:  * This interface describes the basic method a concrete state class needs to
ingo@796:  * implement.
sascha@803:  *
sascha@780:  * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
sascha@780:  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
sascha@780:  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
tim@335:  */
tim@335: public interface State extends Serializable {
tim@335: 
ingo@796:     /**
ingo@796:      * Setup the state.
ingo@796:      *
ingo@796:      * @param configuration State configuration.
ingo@796:      */
tim@335:     public void setup(Node configuration);
tim@335: 
ingo@796:     /**
ingo@796:      * Return the id of the state.
ingo@796:      *
ingo@796:      * @return the id.
ingo@796:      */
tim@335:     public String getID();
tim@335: 
ingo@796:     /**
ingo@796:      * Return the description of the state.
ingo@796:      *
ingo@796:      * @return the description of the state.
ingo@796:      */
tim@335:     public String getDescription();
tim@335: 
ingo@796:     /**
ingo@796:      * This method is called when an artifacts retrieves a describe request. It
ingo@796:      * creates the user interface description of the current state.
ingo@796:      *
ingo@796:      * @param document Describe doucment.
ingo@796:      * @param rootNode Parent node for all new xml elements.
ingo@796:      * @param context The CallContext.
ingo@796:      * @param uuid The uuid of an artifact.
ingo@796:      */
ingo@493:     public void describe(
ingo@493:         Document    document,
ingo@493:         Node        rootNode,
ingo@493:         CallContext context,
ingo@493:         String      uuid
ingo@493:     );
tim@335: 
ingo@796:     /**
ingo@796:      * This method is used to insert new data into this state. Concrete
ingo@796:      * subclasses should valide the input before saving it.
ingo@796:      *
ingo@796:      * @param context The CallContext.
ingo@796:      * @param inputData New InputData items.
ingo@796:      * @param uuid The uuid of an artifact.
ingo@796:      * @return a document with an error or sucess message.
ingo@796:      * @throws StateException
ingo@796:      */
ingo@725:     public Document feed(
ingo@725:         CallContext context, Collection<InputData> inputData, String uuid)
ingo@607:     throws StateException;
ingo@607: 
ingo@796:     /**
ingo@796:      * Set the previous state.
ingo@796:      *
ingo@796:      * @param state The previous state.
ingo@796:      */
tim@335:     public void setParent(State state);
tim@335: 
ingo@796:     /**
ingo@796:      * Returns the previous state.
ingo@796:      *
ingo@796:      * @return the previous state.
ingo@796:      */
tim@335:     public State getParent();
tim@335: 
ingo@796:     /**
ingo@796:      * Retrieve a collection of required input values.
ingo@796:      *
ingo@796:      * @return required input values.
ingo@796:      */
tim@335:     public Collection<InputValue> getRequiredInputValues();
tim@335: 
ingo@796:     /**
ingo@796:      * Retrieves a map with InputData items.
ingo@796:      *
ingo@796:      * @return a map with InputData items.
ingo@796:      */
ingo@473:     public Map<String, InputData> inputData();
ingo@473: 
ingo@796:     /**
ingo@796:      * Use this method to feed a state with some data.
ingo@796:      *
ingo@796:      * @param inputData InputData collection.
ingo@796:      * @param uuid UUID of an artifact.
ingo@796:      * @throws StateException
ingo@796:      */
ingo@493:     public void putInputData(Collection<InputData> inputData, String uuid)
ingo@493:     throws StateException;
tim@335: 
ingo@796:     /**
ingo@796:      * Retrieves a collection with the InputData stored in this state.
ingo@796:      *
ingo@796:      * @return An InputData collection.
ingo@796:      * @throws StateException
ingo@796:      */
tim@335:     public Collection<InputData> getInputData() throws StateException;
tim@335: 
ingo@796:     /**
ingo@796:      * This method is called to advance to a next or previous state.
ingo@796:      *
ingo@796:      * @param uuid The uuid of an artifact.
ingo@796:      * @param context The CallContext object.
ingo@796:      * @throws StateException
ingo@796:      */
ingo@493:     public void advance(String uuid, CallContext context)
ingo@493:     throws StateException;
ingo@493: 
ingo@796:     /**
ingo@796:      * This method is called when the state is created.
ingo@796:      *
ingo@796:      * @param uuid The uuid of an artifact.
ingo@796:      * @param context The CallContext object.
ingo@796:      * @throws StateException
ingo@796:      */
ingo@493:     public void initialize(String uuid, CallContext context)
ingo@493:     throws StateException;
ingo@493: 
ingo@796:     /**
ingo@796:      * This method can be used to reset the state.
ingo@796:      *
ingo@796:      * @param uuid The uuid of an artifact.
ingo@796:      */
ingo@470:     public void reset(String uuid);
sascha@481: 
ingo@796:     /**
ingo@796:      * This method is called when the lifetime of an artifact ends or if the
ingo@796:      * user decides to step back to a previous state.
ingo@796:      *
ingo@796:      * @param globalContext The CallContext.
ingo@796:      */
sascha@481:     public void endOfLife(Object globalContext);
tim@598: 
ingo@796:     /**
ingo@796:      * This method is used to put some InputData objects into an artifact before
ingo@796:      * the parameterization begins.
ingo@796:      *
ingo@796:      * @param preSettings
ingo@796:      */
tim@598:     public void setPreSettings(Map<String,InputData> preSettings);
tim@612: 
ingo@796:     /**
ingo@796:      * This method retrieves a map with InputData objects which have been
ingo@796:      * inserted into this state before the parameterization has started. The key
ingo@796:      * used to store the objects is the name of the state.
ingo@796:      *
ingo@796:      * @return map with InputData objects.
ingo@796:      */
tim@612:     public Map<String,InputData> getPreSettings();
ingo@759: 
ingo@796:     /**
ingo@796:      * Method to remove the data stored at a state which should not be
ingo@796:      * serialized while an artifact is exported.
sascha@803:      *
ingo@796:      * @param context The CallContext
ingo@796:      */
ingo@759:     public void cleanup(Object context);
tim@335: }
sascha@836: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf-8 :