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: *
  1. {@link #identifier() identifier()}: Returns a gobally unique identfier sascha@1: * of this artifact.
    2. sascha@2: *
  2. {@link #hash() hash()}: Returns a hash value over the internal state sascha@1: * of this artifact.
    3. sascha@78: *
  3. {@link #describe(Document, CallContext)}: Returns a description of this artifact.
    4. sascha@78: *
  4. {@link #advance(Document, CallContext) advance()}: Advances this artifact sascha@1: * to the next internal state
    5. sascha@78: *
  5. {@link #feed(Document, CallContext) feed()}: Feed new data into this artifact.
    6. sascha@32: *
  6. {@link #out(Document, OutputStream, CallContext) out()}: Produces output for this artifact.
    7. sascha@1: *
sascha@1: * sascha@10: * There are two more methods involved with the life cycle of the are: sascha@10: *
    sascha@86: *
  1. {@link #setup(String, ArtifactFactory, Object, Document) setup()}: sascha@78: * Called after created by the factory.
    2. sascha@10: *
  2. {@link #endOfLife(Object) endOfLife()}: Called when the artifact sascha@10: * is going to be removed from sascha@10: * system. Useful to clean up.
    3. 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@1: * Produce output from 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: /** sascha@10: * When created by a factory this method is called to sascha@10: * initialize the artifact. 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, 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 :