Mercurial > dive4elements > framework
diff artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java @ 85:78263e910675
Completed Javadoc of sub module 'artifacts'.
artifacts/trunk@831 c6561f87-3c4e-4783-a992-168aeb5c3f6f
author | Sascha L. Teichmann <sascha.teichmann@intevation.de> |
---|---|
date | Fri, 26 Mar 2010 09:41:38 +0000 |
parents | f69e5b87f05f |
children | 933bbc9fc11f |
line wrap: on
line diff
--- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java Fri Mar 26 09:41:38 2010 +0000 @@ -12,8 +12,18 @@ */ public interface ArtifactDatabase { + /** + * Implementations of this class defer the out call. + */ public interface DeferredOutput { + /** + * Inside this method the Artifact.out() method is called + * with the given Outputstream. + * @param output The stream to write the out() output into. + * @throws IOException Thrown if an exception occurs while writing to + * the output stream. + */ void write(OutputStream output) throws IOException; } // interface DeferredOut @@ -24,33 +34,141 @@ */ String [][] artifactFactoryNamesAndDescriptions(); + /** + * The methods returns a 'pure' factory which is not bound to + * the artifact database. This means when an artifact is created + * with the factory the created artifact is not stored in the + * artifact database. + * @param factoryName The name of the queried artifact factory. + * @return The queried artifact factory or null if corresponing + * factory is found. + */ ArtifactFactory getInternalArtifactFactory(String factoryName); - Document createArtifactWithFactory(String factory, - CallMeta callMeta, - Document data) - throws ArtifactDatabaseException; + /** + * Used to create an artifact with the factory which given + * by the name 'factory'. The artifact is stored inside the + * artifact database. If the creation succeeds the describe + * document of the artifact is returned. + * @param factory The name of the factory to create the artifact. + * @param callMeta The meta information (languages et. al.) of the + * creation. + * @param data Optional input data to parameterize the creation. + * @return The describe document of new artifact. + * @throws ArtifactDatabaseException Thrown if something went wrong + * during artifact creation. + */ + Document createArtifactWithFactory( + String factory, + CallMeta callMeta, + Document data + ) throws ArtifactDatabaseException; + /** + * Returns the describe document of artifact identified + * with the string 'artifact'. + * @param artifact The identifier of the artifact. + * @param data Optional input data to parameterize the description. + * @param callMeta the meta information (language et. al.) of + * the description. + * @return The describe document of the artifact. + * @throws ArtifactDatabaseException Thrown id something went wrong + * during the creation of the describe document. + */ Document describe(String artifact, Document data, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * Advances the artifact identified by 'artifact' to the state + * 'target'. The result of the attempt is returned. + * @param artifact The identifier of the artifact. + * @param target The target state of the advance attempt. + * @param callMeta The meta information (language et. al.) of the + * advance attempt. + * @return The result document of the advance attempt. + * @throws ArtifactDatabaseException Thrown if something went wrong + * during the advance attempt. + */ Document advance(String artifact, Document target, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * Feeds the artifact identified by 'artifact' with some data 'data'. + * @param artifact The identifier of the artifact. + * @param data The data to be fed into the artifact. + * @param callMeta The meta information (language et. al.) of the feed + * attempt. + * @return The result of the feed attempt. + * @throws ArtifactDatabaseException Throw if something went wrong during + * the feed attempt. + */ Document feed(String artifact, Document data, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * Produces output for a given artifact identified by 'artifact' in + * a requested format 'format'. The writing of the data is done when + * the write() method of the returned DeferredOutput is called. This + * optimizes the out streaming of the data because the call can be + * deferred into to the calling context. + * @param artifact The identifier of the artifact. + * @param format The request format of the output. + * @param callMeta The meta information (language et. al.) of the output. + * @return The deferred output to be written later in the calling context. + * @throws ArtifactDatabaseException Thrown if something went wrong during + * producing the output. + */ DeferredOutput out(String artifact, Document format, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * Produces an extenal represention of the artifact identified by + * 'artifact' to be re-imported by #importArtifact(Document, CallMeta) + * later. + * @param artifact The identifier of the artifact. + * @param callMeta The meta informatio (language et. al.) of the export. + * @return A extenal representation of the artifact. + * @throws ArtifactDatabaseException Thrown if something went wrong + * during export. + */ Document exportArtifact(String artifact, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * The symmetrical counter part of #exportArtifact(String, CallMeta). + * It attempts to import the artifact which is coded inside the 'data' + * document. When the import succeeds the new artifact is given a new + * internal identifier and the describe document of the artifact is + * returned. + * @param data The encoded artifact. Has to be the output of + * #exportArtifact(String, CallMeta). + * @param callMeta The meta information (language et. al.) of the + * import. + * @return The describe document of the imported artifact. + * @throws ArtifactDatabaseException Thrown if something went wrong during + * the import attempt. + */ Document importArtifact(Document data, CallMeta callMeta) throws ArtifactDatabaseException; + /** + * Returns a list of services offered by this artifact database. + * @return The array returned contains tuples of (name, description) + * strings. + */ String [][] serviceNamesAndDescriptions(); + /** + * Calls a service identified by 'service' with input document 'input' + * to produce some output document. + * @param service The name of the service. + * @param input The input document. + * @param callMeta The meta information (language et. al.) of the + * service call. + * @return The result document produced by the service. + * @throws ArtifactDatabaseException Thrown if someting went wrong during + * the service processing. + */ Document process(String service, Document input, CallMeta callMeta) throws ArtifactDatabaseException; }