ingo@100: /*
ingo@100: * Copyright (c) 2010 by Intevation GmbH
ingo@100: *
ingo@100: * This program is free software under the LGPL (>=v2.1)
ingo@100: * Read the file LGPL.txt coming with the software for details
ingo@100: * or visit http://www.gnu.org/licenses/ if it does not exist.
ingo@100: */
ingo@100:
sascha@1: package de.intevation.artifacts;
sascha@1:
tim@75: import java.io.IOException;
tim@75: import java.io.OutputStream;
tim@75: import java.io.Serializable;
tim@75:
sascha@1: import org.w3c.dom.Document;
sascha@1:
sascha@1: /**
sascha@1: * Interface of the core component of the artifact system: The artifact.
sascha@1: *
sascha@1: *
sascha@1: * An artifact is an abstract data type offering the following methods:
sascha@1: *
sascha@1: *
sascha@1: * - {@link #identifier() identifier()}: Returns a gobally unique identfier
sascha@1: * of this artifact.
sascha@2: * - {@link #hash() hash()}: Returns a hash value over the internal state
sascha@1: * of this artifact.
sascha@78: * - {@link #describe(Document, CallContext)}: Returns a description of this artifact.
sascha@78: * - {@link #advance(Document, CallContext) advance()}: Advances this artifact
sascha@1: * to the next internal state
sascha@78: * - {@link #feed(Document, CallContext) feed()}: Feed new data into this artifact.
sascha@32: * - {@link #out(Document, OutputStream, CallContext) out()}: Produces output for this artifact.
sascha@1: *
sascha@1: *
sascha@10: * There are two more methods involved with the life cycle of the are:
sascha@10: *
felix@326: * - {@link #setup(String, ArtifactFactory, Object, CallMeta, Document) setup()}:
sascha@78: * Called after created by the factory.
sascha@10: * - {@link #endOfLife(Object) endOfLife()}: Called when the artifact
sascha@10: * is going to be removed from
sascha@10: * system. Useful to clean up.
sascha@10: *
sascha@10: *
sascha@77: * @author Sascha L. Teichmann
sascha@1: */
sascha@1: public interface Artifact
sascha@1: extends Serializable
sascha@1: {
ingo@81:
ingo@81: /**
ingo@81: * Set a new identifier for this artifact.
ingo@81: * @param identifier New identifier for this artifact.
ingo@81: */
ingo@81: public void setIdentifier(String identifier);
ingo@81:
sascha@1: /**
sascha@1: * Identify this artifact.
sascha@1: * @return Returns unique string to identify this artifact globally.
sascha@1: */
sascha@32: 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@32: String hash();
sascha@1:
sascha@1: /**
sascha@1: * A description used to build a interface to interact with this artifact.
sascha@78: * @param data General input data. Useful to produces specific descriptions.
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@55: Document describe(Document data, CallContext 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@32: Document advance(Document target, CallContext 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@32: Document feed(Document data, CallContext context);
sascha@1:
sascha@1: /**
sascha@115: * Produce output for this artifact.
sascha@1: * @param format Specifies the format of the output.
sascha@78: * @param out Stream to write the result data to.
sascha@4: * @param context The global context of the runtime system.
sascha@78: * @throws IOException Thrown if an I/O occurs.
sascha@1: */
sascha@32: void out(
sascha@31: Document format,
sascha@47: OutputStream out,
sascha@32: CallContext context)
sascha@31: throws IOException;
sascha@9:
sascha@9: /**
ingo@269: * Produce output for this artifact.
ingo@269: * @param type Specifies the type of the output.
ingo@269: * @param format Specifies the format of the output.
ingo@269: * @param out Stream to write the result data to.
ingo@269: * @param context The global context of the runtime system.
ingo@269: * @throws IOException Thrown if an I/O occurs.
ingo@269: */
ingo@269: void out(
ingo@269: String type,
ingo@269: Document format,
ingo@269: OutputStream out,
ingo@269: CallContext context)
ingo@269: throws IOException;
ingo@269:
ingo@269: /**
sascha@10: * When created by a factory this method is called to
sascha@10: * initialize the artifact.
felix@326: *
sascha@10: * @param identifier The identifier from artifact database
sascha@24: * @param factory The factory which created this artifact.
sascha@10: * @param context The global context of the runtime system.
sascha@86: * @param data The data which can be use to setup an artifact with
tim@75: * more details.
sascha@10: */
sascha@32: public void setup(
sascha@47: String identifier,
sascha@32: ArtifactFactory factory,
tim@75: Object context,
ingo@297: CallMeta callMeta,
sascha@78: Document data);
sascha@10:
sascha@10: /**
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);
ingo@82:
ingo@82:
ingo@82: /**
ingo@82: * Called from artifact database before an artifact is
ingo@82: * going to be exported as xml document.
sascha@85: * @param context The global context of the runtime system.
ingo@82: */
ingo@82: public void cleanup(Object context);
sascha@1: }
sascha@85: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :