Mercurial > dive4elements > framework

comparison artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java @ 85:78263e910675

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
84:72e2dd4feb31 85:78263e910675
10 * 10 *
11 * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a> 11 * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
12 */ 12 */
13 public interface ArtifactDatabase 13 public interface ArtifactDatabase
14 { 14 {
15 /**
16 * Implementations of this class defer the out call.
17 */
15 public interface DeferredOutput { 18 public interface DeferredOutput {
16 19
20 /**
21 * Inside this method the Artifact.out() method is called
22 * with the given Outputstream.
23 * @param output The stream to write the out() output into.
24 * @throws IOException Thrown if an exception occurs while writing to
25 * the output stream.
26 */
17 void write(OutputStream output) throws IOException; 27 void write(OutputStream output) throws IOException;
18 28
19 } // interface DeferredOut 29 } // interface DeferredOut
20 30
21 /** 31 /**
22 * List of artifact factories names accessible through the database. 32 * List of artifact factories names accessible through the database.
23 * @return pairs of names and descriptions of the factories. 33 * @return pairs of names and descriptions of the factories.
24 */ 34 */
25 String [][] artifactFactoryNamesAndDescriptions(); 35 String [][] artifactFactoryNamesAndDescriptions();
26 36
37 /**
38 * The methods returns a 'pure' factory which is not bound to
39 * the artifact database. This means when an artifact is created
40 * with the factory the created artifact is not stored in the
41 * artifact database.
42 * @param factoryName The name of the queried artifact factory.
43 * @return The queried artifact factory or null if corresponing
44 * factory is found.
45 */
27 ArtifactFactory getInternalArtifactFactory(String factoryName); 46 ArtifactFactory getInternalArtifactFactory(String factoryName);
28 47
29 Document createArtifactWithFactory(String factory, 48 /**
30 CallMeta callMeta, 49 * Used to create an artifact with the factory which given
31 Document data) 50 * by the name 'factory'. The artifact is stored inside the
32 throws ArtifactDatabaseException; 51 * artifact database. If the creation succeeds the describe
52 * document of the artifact is returned.
53 * @param factory The name of the factory to create the artifact.
54 * @param callMeta The meta information (languages et. al.) of the
55 * creation.
56 * @param data Optional input data to parameterize the creation.
57 * @return The describe document of new artifact.
58 * @throws ArtifactDatabaseException Thrown if something went wrong
59 * during artifact creation.
60 */
61 Document createArtifactWithFactory(
62 String factory,
63 CallMeta callMeta,
64 Document data
65 ) throws ArtifactDatabaseException;
33 66
67 /**
68 * Returns the describe document of artifact identified
69 * with the string 'artifact'.
70 * @param artifact The identifier of the artifact.
71 * @param data Optional input data to parameterize the description.
72 * @param callMeta the meta information (language et. al.) of
73 * the description.
74 * @return The describe document of the artifact.
75 * @throws ArtifactDatabaseException Thrown id something went wrong
76 * during the creation of the describe document.
77 */
34 Document describe(String artifact, Document data, CallMeta callMeta) 78 Document describe(String artifact, Document data, CallMeta callMeta)
35 throws ArtifactDatabaseException; 79 throws ArtifactDatabaseException;
36 80
81 /**
82 * Advances the artifact identified by 'artifact' to the state
83 * 'target'. The result of the attempt is returned.
84 * @param artifact The identifier of the artifact.
85 * @param target The target state of the advance attempt.
86 * @param callMeta The meta information (language et. al.) of the
87 * advance attempt.
88 * @return The result document of the advance attempt.
89 * @throws ArtifactDatabaseException Thrown if something went wrong
90 * during the advance attempt.
91 */
37 Document advance(String artifact, Document target, CallMeta callMeta) 92 Document advance(String artifact, Document target, CallMeta callMeta)
38 throws ArtifactDatabaseException; 93 throws ArtifactDatabaseException;
39 94
95 /**
96 * Feeds the artifact identified by 'artifact' with some data 'data'.
97 * @param artifact The identifier of the artifact.
98 * @param data The data to be fed into the artifact.
99 * @param callMeta The meta information (language et. al.) of the feed
100 * attempt.
101 * @return The result of the feed attempt.
102 * @throws ArtifactDatabaseException Throw if something went wrong during
103 * the feed attempt.
104 */
40 Document feed(String artifact, Document data, CallMeta callMeta) 105 Document feed(String artifact, Document data, CallMeta callMeta)
41 throws ArtifactDatabaseException; 106 throws ArtifactDatabaseException;
42 107
108 /**
109 * Produces output for a given artifact identified by 'artifact' in
110 * a requested format 'format'. The writing of the data is done when
111 * the write() method of the returned DeferredOutput is called. This
112 * optimizes the out streaming of the data because the call can be
113 * deferred into to the calling context.
114 * @param artifact The identifier of the artifact.
115 * @param format The request format of the output.
116 * @param callMeta The meta information (language et. al.) of the output.
117 * @return The deferred output to be written later in the calling context.
118 * @throws ArtifactDatabaseException Thrown if something went wrong during
119 * producing the output.
120 */
43 DeferredOutput out(String artifact, Document format, CallMeta callMeta) 121 DeferredOutput out(String artifact, Document format, CallMeta callMeta)
44 throws ArtifactDatabaseException; 122 throws ArtifactDatabaseException;
45 123
124 /**
125 * Produces an extenal represention of the artifact identified by
126 * 'artifact' to be re-imported by #importArtifact(Document, CallMeta)
127 * later.
128 * @param artifact The identifier of the artifact.
129 * @param callMeta The meta informatio (language et. al.) of the export.
130 * @return A extenal representation of the artifact.
131 * @throws ArtifactDatabaseException Thrown if something went wrong
132 * during export.
133 */
46 Document exportArtifact(String artifact, CallMeta callMeta) 134 Document exportArtifact(String artifact, CallMeta callMeta)
47 throws ArtifactDatabaseException; 135 throws ArtifactDatabaseException;
48 136
137 /**
138 * The symmetrical counter part of #exportArtifact(String, CallMeta).
139 * It attempts to import the artifact which is coded inside the 'data'
140 * document. When the import succeeds the new artifact is given a new
141 * internal identifier and the describe document of the artifact is
142 * returned.
143 * @param data The encoded artifact. Has to be the output of
144 * #exportArtifact(String, CallMeta).
145 * @param callMeta The meta information (language et. al.) of the
146 * import.
147 * @return The describe document of the imported artifact.
148 * @throws ArtifactDatabaseException Thrown if something went wrong during
149 * the import attempt.
150 */
49 Document importArtifact(Document data, CallMeta callMeta) 151 Document importArtifact(Document data, CallMeta callMeta)
50 throws ArtifactDatabaseException; 152 throws ArtifactDatabaseException;
51 153
154 /**
155 * Returns a list of services offered by this artifact database.
156 * @return The array returned contains tuples of (name, description)
157 * strings.
158 */
52 String [][] serviceNamesAndDescriptions(); 159 String [][] serviceNamesAndDescriptions();
53 160
161 /**
162 * Calls a service identified by 'service' with input document 'input'
163 * to produce some output document.
164 * @param service The name of the service.
165 * @param input The input document.
166 * @param callMeta The meta information (language et. al.) of the
167 * service call.
168 * @return The result document produced by the service.
169 * @throws ArtifactDatabaseException Thrown if someting went wrong during
170 * the service processing.
171 */
54 Document process(String service, Document input, CallMeta callMeta) 172 Document process(String service, Document input, CallMeta callMeta)
55 throws ArtifactDatabaseException; 173 throws ArtifactDatabaseException;
56 } 174 }
57 // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : 175 // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
http://dive4elements.wald.intevation.org