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: 
teichmann@475: package org.dive4elements.artifacts;
sascha@1: 
tim@75: import java.io.IOException;
tim@75: import java.io.OutputStream;
tim@75: 
sascha@32: import org.w3c.dom.Document;
sascha@32: 
sascha@320: import java.util.Date;
gernotbelger@562: import java.util.Map;
sascha@320: 
sascha@1: /**
sascha@1:  * Interface of an artifact managing database.
sascha@1:  *
sascha@77:  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
sascha@1:  */
sascha@1: public interface ArtifactDatabase
sascha@1: {
sascha@85:     /**
sascha@85:      * Implementations of this class defer the out call.
sascha@85:      */
sascha@32:     public interface DeferredOutput {
sascha@1: 
sascha@85:         /**
sascha@85:          * Inside this method the Artifact.out() method is called
sascha@85:          * with the given Outputstream.
sascha@85:          * @param output The stream to write the out() output into.
sascha@85:          * @throws IOException Thrown if an exception occurs while writing to
sascha@85:          * the output stream.
sascha@85:          */
sascha@32:         void write(OutputStream output) throws IOException;
sascha@32: 
sascha@32:     } // interface DeferredOut
sascha@1: 
sascha@1:     /**
sascha@32:      * List of artifact factories names accessible through the database.
sascha@32:      * @return pairs of names and descriptions of the factories.
sascha@1:      */
sascha@32:     String [][] artifactFactoryNamesAndDescriptions();
sascha@4: 
sascha@85:     /**
sascha@85:      * The methods returns a 'pure' factory which is not bound to
sascha@85:      * the artifact database. This means when an artifact is created
sascha@85:      * with the factory the created artifact is  not stored in the
sascha@85:      * artifact database.
sascha@85:      * @param factoryName The name of the queried artifact factory.
sascha@85:      * @return The queried artifact factory or null if corresponing
sascha@85:      * factory is found.
sascha@85:      */
ingo@66:     ArtifactFactory getInternalArtifactFactory(String factoryName);
ingo@66: 
sascha@85:     /**
sascha@85:      * Used to create an artifact with the factory which given
sascha@85:      * by the name 'factory'. The artifact is stored inside the
sascha@85:      * artifact database. If the creation succeeds the describe
sascha@85:      * document of the artifact is returned.
sascha@85:      * @param factory The name of the factory to create the artifact.
sascha@85:      * @param callMeta The meta information (languages et. al.) of the
sascha@85:      * creation.
sascha@85:      * @param data Optional input data to parameterize the creation.
sascha@85:      * @return The describe document of new artifact.
sascha@85:      * @throws ArtifactDatabaseException Thrown if something went wrong
sascha@85:      * during artifact creation.
sascha@85:      */
sascha@85:     Document createArtifactWithFactory(
sascha@85:         String   factory,
sascha@85:         CallMeta callMeta,
sascha@85:         Document data
sascha@85:     ) throws ArtifactDatabaseException;
sascha@32: 
sascha@85:     /**
ingo@293:      * Used to retrieve an artifact.<b>NOTE: artifact modifications are not
ingo@293:      * persisted to database!</b>
ingo@293:      */
ingo@293:     Artifact getRawArtifact(String identifier)
ingo@293:     throws ArtifactDatabaseException;
ingo@293: 
ingo@293:     /**
sascha@85:      * Returns the describe document of artifact identified
sascha@85:      * with the string 'artifact'.
sascha@85:      * @param artifact The identifier of the artifact.
sascha@85:      * @param data Optional input data to parameterize the description.
sascha@85:      * @param callMeta the meta information (language et. al.) of
sascha@85:      * the description.
sascha@85:      * @return The describe document of the artifact.
sascha@85:      * @throws ArtifactDatabaseException Thrown id something went wrong
sascha@85:      * during the creation of the describe document.
sascha@85:      */
sascha@55:     Document describe(String artifact, Document data, CallMeta callMeta)
sascha@32:         throws ArtifactDatabaseException;
sascha@32: 
sascha@85:     /**
sascha@85:      * Advances the artifact identified by 'artifact' to the state
sascha@85:      * 'target'. The result of the attempt is returned.
sascha@85:      * @param artifact The identifier of the artifact.
sascha@85:      * @param target The target state of the advance attempt.
sascha@85:      * @param callMeta The meta information (language et. al.) of the
sascha@85:      * advance attempt.
sascha@85:      * @return The result document of the advance attempt.
sascha@85:      * @throws ArtifactDatabaseException Thrown if something went wrong
sascha@85:      * during the advance attempt.
sascha@85:      */
sascha@48:     Document advance(String artifact, Document target, CallMeta callMeta)
sascha@32:         throws ArtifactDatabaseException;
sascha@32: 
sascha@85:     /**
sascha@85:      * Feeds the artifact identified by 'artifact' with some data 'data'.
sascha@85:      * @param artifact The identifier of the artifact.
sascha@85:      * @param data The data to be fed into the artifact.
sascha@85:      * @param callMeta The meta information (language et. al.) of the feed
sascha@85:      * attempt.
sascha@85:      * @return The result of the feed attempt.
sascha@85:      * @throws ArtifactDatabaseException Throw if something went wrong during
sascha@85:      * the feed attempt.
sascha@85:      */
sascha@48:     Document feed(String artifact, Document data, CallMeta callMeta)
sascha@48:         throws ArtifactDatabaseException;
sascha@48: 
sascha@85:     /**
sascha@85:      * Produces output for a given artifact identified by 'artifact' in
sascha@85:      * a requested format 'format'. The writing of the data is done when
sascha@85:      * the write() method of the returned DeferredOutput is called. This
sascha@85:      * optimizes the out streaming of the data because the call can be
sascha@85:      * deferred into to the calling context.
sascha@85:      * @param artifact The identifier of the artifact.
sascha@85:      * @param format The request format of the output.
sascha@85:      * @param callMeta The meta information (language et. al.) of the output.
sascha@85:      * @return The deferred output to be written later in the calling context.
sascha@85:      * @throws ArtifactDatabaseException Thrown if something went wrong during
sascha@85:      * producing the output.
sascha@85:      */
sascha@48:     DeferredOutput out(String artifact, Document format, CallMeta callMeta)
sascha@32:         throws ArtifactDatabaseException;
sascha@32: 
ingo@269: 
ingo@269:     /**
ingo@269:      * Produces output for a given artifact identified by 'artifact' in
ingo@269:      * a requested format 'format'. The writing of the data is done when
ingo@269:      * the write() method of the returned DeferredOutput is called. This
ingo@269:      * optimizes the out streaming of the data because the call can be
ingo@269:      * deferred into to the calling context.
ingo@269:      * @param artifact The identifier of the artifact.
ingo@269:      * @param format The request format of the output.
ingo@269:      * @param callMeta The meta information (language et. al.) of the output.
ingo@269:      * @return The deferred output to be written later in the calling context.
ingo@269:      * @throws ArtifactDatabaseException Thrown if something went wrong during
ingo@269:      * producing the output.
ingo@269:      */
ingo@269:     DeferredOutput out(
ingo@269:         String   artifact,
ingo@269:         String   type,
ingo@269:         Document format,
ingo@269:         CallMeta callMeta)
ingo@269:     throws ArtifactDatabaseException;
ingo@269: 
sascha@85:     /**
sascha@85:      * Produces an extenal represention of the artifact identified by
sascha@85:      * 'artifact' to be re-imported by #importArtifact(Document, CallMeta)
sascha@85:      * later.
sascha@85:      * @param artifact The identifier of the artifact.
sascha@85:      * @param callMeta The meta informatio (language et. al.) of the export.
sascha@85:      * @return A extenal representation of the artifact.
sascha@85:      * @throws ArtifactDatabaseException Thrown if something went wrong
sascha@85:      * during export.
sascha@85:      */
ingo@79:     Document exportArtifact(String artifact, CallMeta callMeta)
ingo@79:         throws ArtifactDatabaseException;
ingo@79: 
sascha@85:     /**
sascha@85:      * The symmetrical counter part of #exportArtifact(String, CallMeta).
sascha@85:      * It attempts to import the artifact which is coded inside the 'data'
sascha@85:      * document. When the import succeeds the new artifact is given a new
sascha@85:      * internal identifier and the describe document of the artifact is
sascha@85:      * returned.
sascha@85:      * @param data The encoded artifact. Has to be the output of
sascha@85:      * #exportArtifact(String, CallMeta).
sascha@85:      * @param callMeta The meta information (language et. al.) of the
sascha@85:      * import.
sascha@85:      * @return The describe document of the imported artifact.
sascha@85:      * @throws ArtifactDatabaseException Thrown if something went wrong during
sascha@85:      * the import attempt.
sascha@85:      */
ingo@79:     Document importArtifact(Document data, CallMeta callMeta)
ingo@79:         throws ArtifactDatabaseException;
ingo@79: 
sascha@85:     /**
sascha@85:      * Returns a list of services offered by this artifact database.
sascha@85:      * @return The array returned contains tuples of (name, description)
sascha@85:      * strings.
sascha@85:      */
sascha@68:     String [][] serviceNamesAndDescriptions();
sascha@68: 
sascha@85:     /**
sascha@85:      * Calls a service identified by 'service' with input document 'input'
sascha@85:      * to produce some output document.
sascha@85:      * @param service The name of the service.
sascha@85:      * @param input The input document.
sascha@85:      * @param callMeta The meta information (language et. al.) of the
sascha@85:      * service call.
sascha@85:      * @return The result document produced by the service.
sascha@85:      * @throws ArtifactDatabaseException Thrown if someting went wrong during
sascha@85:      * the service processing.
sascha@85:      */
sascha@380:     Service.Output process(String service, Document input, CallMeta callMeta)
sascha@70:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     // User API
sascha@117: 
sascha@117:     Document listUsers(CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
bjoern@415:     Document findUser(Document data, CallMeta callMeta)
bjoern@415:         throws ArtifactDatabaseException;
bjoern@415: 
sascha@117:     Document createUser(Document data, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document deleteUser(String userId, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     // Collection API
sascha@117: 
felix@343:     Document getCollectionsMasterArtifact(String collectionId, CallMeta meta)
felix@343:         throws ArtifactDatabaseException;
felix@343: 
sascha@117:     Document listCollections(String userId, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document createCollection(String ownerId, Document data,
sascha@117:         CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document deleteCollection(String collectionId, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
ingo@196:     Document describeCollection(String collectionId, CallMeta callMeta)
ingo@196:         throws ArtifactDatabaseException;
ingo@196: 
ingo@253:     Document getCollectionAttribute(String collectionId, CallMeta callMeta)
ingo@253:     throws ArtifactDatabaseException;
ingo@253: 
ingo@253:     Document setCollectionAttribute(
ingo@253:         String   collectionId,
ingo@253:         CallMeta callMeta,
ingo@253:         Document attribute)
ingo@253:     throws ArtifactDatabaseException;
ingo@253: 
ingo@252:     Document getCollectionItemAttribute(String collectionId, String artifactId,
sascha@117:         CallMeta callMeta) throws ArtifactDatabaseException;
sascha@117: 
ingo@252:     Document setCollectionItemAttribute(String collectionId, String artifactId,
sascha@117:         Document attribute, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document addCollectionArtifact(String collectionId, String artifactId,
ingo@189:         Document input, CallMeta callMeta) throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document removeCollectionArtifact(String collectionId, String artifactId,
sascha@117:         CallMeta callMeta) throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     Document listCollectionArtifacts(String collectionId,
sascha@117:         CallMeta callMeta) throws ArtifactDatabaseException;
sascha@117: 
sascha@117:     DeferredOutput outCollection(String collectionId,
sascha@117:         Document format, CallMeta callMeta)
sascha@117:         throws ArtifactDatabaseException;
ingo@269: 
ingo@269:     DeferredOutput outCollection(String collectionId, String type,
ingo@269:         Document format, CallMeta callMeta)
ingo@269:         throws ArtifactDatabaseException;
ingo@273: 
ingo@273:     Document setCollectionTTL(String collectionId, Document doc, CallMeta meta)
ingo@273:     throws ArtifactDatabaseException;
ingo@275: 
ingo@275:     Document setCollectionName(String collectionId, Document doc, CallMeta meta)
ingo@275:     throws ArtifactDatabaseException;
sascha@303: 
sascha@303:     public interface ArtifactLoadedCallback {
sascha@303:         void artifactLoaded(
sascha@303:             String   userId,
sascha@303:             String   collectionId,
sascha@317:             String   collectionName,
sascha@320:             Date     collectionCreated,
sascha@303:             String   artifactId,
sascha@320:             Date     artifactCreated,
sascha@303:             Artifact artifact);
gernotbelger@550:     }
sascha@303: 
sascha@303:     public void loadAllArtifacts(ArtifactLoadedCallback callback)
sascha@303:         throws ArtifactDatabaseException;
gernotbelger@550: 
gernotbelger@550:     String findArtifactUser(String artifactIdentifier);
gernotbelger@562: 
gernotbelger@562:     String getServerAddress();
gernotbelger@562: 
gernotbelger@562:     /** an additional list of rest services (path and implementing class) that should be registered */
gernotbelger@562:     Map<String, Class<?>> getRestServices();
sascha@1: }
ingo@79: // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :