sascha@1: package de.intevation.artifacts;
sascha@1: 
sascha@1: import org.w3c.dom.Document;
sascha@1: 
sascha@1: import java.io.Serializable;
sascha@1: 
sascha@1: /**
sascha@1:  * Interface of the core component of the artifact system: <strong>The artifact</strong>.
sascha@1:  * <br>
sascha@1:  *
sascha@1:  * An artifact is an abstract data type offering the following methods:
sascha@1:  *
sascha@1:  * <ol>
sascha@1:  *   <li>{@link #identifier() identifier()}: Returns a gobally unique identfier
sascha@1:  *        of this artifact.</li>
sascha@2:  *   <li>{@link #hash() hash()}: Returns a hash value over the internal state
sascha@1:  *        of this artifact.</li>
sascha@4:  *   <li>{@link #describe(Object)}: Returns a description of this artifact.</li>
sascha@4:  *   <li>{@link #advance(Document, Object) advance()}: Advances this artifact
sascha@1:  *       to the next internal state</li>
sascha@4:  *   <li>{@link #feed(Document, Object) feed()}: Feed new data into this artifact.</li>
sascha@4:  *   <li>{@link #out(Document, Object) out()}: Produces output for this artifact.</li>
sascha@1:  * </ol>
sascha@1:  *
sascha@1:  * @author Sascha L. Teichmann (sascha.teichmann@intevation.de)
sascha@1:  */
sascha@1: public interface Artifact
sascha@1: extends          Serializable
sascha@1: {
sascha@1:     /**
sascha@1:      * Identify this artifact.
sascha@1:      * @return Returns unique string to identify this artifact globally.
sascha@1:      */
sascha@1:     public String identifier();
sascha@1: 
sascha@1:     /**
sascha@1:      * Internal hash of this artifact.
sascha@1:      * @return Returns hash that should stay the same if the internal
sascha@1:      *         value has not changed. Useful for caching
sascha@1:      */
sascha@1:     public String hash();
sascha@1: 
sascha@1:     /**
sascha@1:      * A description used to build a interface to interact with this artifact.
sascha@4:      * @param context The global context of the runtime system.
sascha@1:      * @return An XML representation of the current state of the artifact.
sascha@1:      */
sascha@4:     public Document describe(Object context);
sascha@1: 
sascha@1:     /**
sascha@1:      * Change the internal state of the artifact.
sascha@1:      * @return An XML representation of the success of the advancing.
sascha@4:      * @param target Target of internal state to move to.
sascha@4:      * @param context The global context of the runtime system.
sascha@1:      */
sascha@4:     public Document advance(Document target, Object context);
sascha@1: 
sascha@1:     /**
sascha@1:      * Feed data into this artifact.
sascha@1:      * @param data Data to feed artifact with.
sascha@4:      * @param context The global context of the runtime system.
sascha@1:      * @return An XML representation of the success of the feeding.
sascha@1:      */
sascha@4:     public Document feed(Document data, Object context);
sascha@1: 
sascha@1:     /**
sascha@1:      * Produce output from this artifact.
sascha@1:      * @param format Specifies the format of the output.
sascha@4:      * @param context The global context of the runtime system.
sascha@1:      * @return a byte representation of the output.
sascha@1:      */
sascha@4:     public byte [] out(Document format, Object context);
sascha@9: 
sascha@9:     /**
sascha@9:      * Called from artifact database when an artifact is
sascha@9:      * going to be removed from system.
sascha@9:      * @param context The global context of the runtime system.
sascha@9:      */
sascha@9:     public void endOfLife(Object context);
sascha@1: }
sascha@1: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: