# HG changeset patch # User Sascha L. Teichmann # Date 1269596498 0 # Node ID 78263e9106756403acd5ea0f0074f6221ee3d440 # Parent 72e2dd4feb31c03d2002c997f68162e24bf93929 Completed Javadoc of sub module 'artifacts'. artifacts/trunk@831 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r 72e2dd4feb31 -r 78263e910675 ChangeLog --- a/ChangeLog Thu Mar 25 17:32:54 2010 +0000 +++ b/ChangeLog Fri Mar 26 09:41:38 2010 +0000 @@ -1,3 +1,18 @@ +2010-03-26 Sascha L. Teichmann + + * artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java, + artifacts/src/main/java/de/intevation/artifacts/Artifact.java: + Completed Javadoc of sub module 'artifacts'. TODO: add Javadoc to + module 'artifact-database' + + * artifacts/src/main/java/de/intevation/artifacts/CallContext.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java, + artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java, + artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java: + Fixed vim modeline. + 2010-03-25 Ingo Weinzierl * artifacts/src/main/java/de/intevation/artifacts/CallContext.java: Added a diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/Artifact.java --- a/artifacts/src/main/java/de/intevation/artifacts/Artifact.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/Artifact.java Fri Mar 26 09:41:38 2010 +0000 @@ -121,7 +121,8 @@ /** * Called from artifact database before an artifact is * going to be exported as xml document. + * @param context The global context of the runtime system. */ public void cleanup(Object context); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactContextFactory.java Fri Mar 26 09:41:38 2010 +0000 @@ -18,4 +18,4 @@ */ Object createArtifactContext(Document config); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java --- 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; } diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabaseException.java Fri Mar 26 09:41:38 2010 +0000 @@ -21,4 +21,4 @@ super(msg); } } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactFactory.java Fri Mar 26 09:41:38 2010 +0000 @@ -59,4 +59,4 @@ */ ArtifactSerializer getSerializer(); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java --- a/artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/ArtifactSerializer.java Fri Mar 26 09:41:38 2010 +0000 @@ -21,4 +21,4 @@ */ byte [] toBytes(Artifact artifact); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/CallContext.java --- a/artifacts/src/main/java/de/intevation/artifacts/CallContext.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/CallContext.java Fri Mar 26 09:41:38 2010 +0000 @@ -90,4 +90,4 @@ */ Long getTimeToLive(); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r 72e2dd4feb31 -r 78263e910675 artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java --- a/artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java Thu Mar 25 17:32:54 2010 +0000 +++ b/artifacts/src/main/java/de/intevation/artifacts/PreferredLocale.java Fri Mar 26 09:41:38 2010 +0000 @@ -20,4 +20,4 @@ */ float getQuality(); } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :