Mercurial > dive4elements > framework

comparison artifacts/src/main/java/org/dive4elements/artifacts/ArtifactDatabase.java @ 471:1a87cb24a446

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Moved directories to org.dive4elements
author Sascha L. Teichmann <teichmann@intevation.de>
date Thu, 25 Apr 2013 10:50:31 +0200
parents artifacts/src/main/java/de/intevation/artifacts/ArtifactDatabase.java@d4a846ee35b8
children 415df0fc4fa1
comparison
equal deleted inserted replaced
470:19cb9729bd17 471:1a87cb24a446
1 /*
2 * Copyright (c) 2010 by Intevation GmbH
3 *
4 * This program is free software under the LGPL (>=v2.1)
5 * Read the file LGPL.txt coming with the software for details
6 * or visit http://www.gnu.org/licenses/ if it does not exist.
7 */
8
9 package de.intevation.artifacts;
10
11 import java.io.IOException;
12 import java.io.OutputStream;
13
14 import org.w3c.dom.Document;
15
16 import java.util.Date;
17
18 /**
19 * Interface of an artifact managing database.
20 *
21 * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
22 */
23 public interface ArtifactDatabase
24 {
25 /**
26 * Implementations of this class defer the out call.
27 */
28 public interface DeferredOutput {
29
30 /**
31 * Inside this method the Artifact.out() method is called
32 * with the given Outputstream.
33 * @param output The stream to write the out() output into.
34 * @throws IOException Thrown if an exception occurs while writing to
35 * the output stream.
36 */
37 void write(OutputStream output) throws IOException;
38
39 } // interface DeferredOut
40
41 /**
42 * List of artifact factories names accessible through the database.
43 * @return pairs of names and descriptions of the factories.
44 */
45 String [][] artifactFactoryNamesAndDescriptions();
46
47 /**
48 * The methods returns a 'pure' factory which is not bound to
49 * the artifact database. This means when an artifact is created
50 * with the factory the created artifact is not stored in the
51 * artifact database.
52 * @param factoryName The name of the queried artifact factory.
53 * @return The queried artifact factory or null if corresponing
54 * factory is found.
55 */
56 ArtifactFactory getInternalArtifactFactory(String factoryName);
57
58 /**
59 * Used to create an artifact with the factory which given
60 * by the name 'factory'. The artifact is stored inside the
61 * artifact database. If the creation succeeds the describe
62 * document of the artifact is returned.
63 * @param factory The name of the factory to create the artifact.
64 * @param callMeta The meta information (languages et. al.) of the
65 * creation.
66 * @param data Optional input data to parameterize the creation.
67 * @return The describe document of new artifact.
68 * @throws ArtifactDatabaseException Thrown if something went wrong
69 * during artifact creation.
70 */
71 Document createArtifactWithFactory(
72 String factory,
73 CallMeta callMeta,
74 Document data
75 ) throws ArtifactDatabaseException;
76
77 /**
78 * Used to retrieve an artifact.<b>NOTE: artifact modifications are not
79 * persisted to database!</b>
80 */
81 Artifact getRawArtifact(String identifier)
82 throws ArtifactDatabaseException;
83
84 /**
85 * Returns the describe document of artifact identified
86 * with the string 'artifact'.
87 * @param artifact The identifier of the artifact.
88 * @param data Optional input data to parameterize the description.
89 * @param callMeta the meta information (language et. al.) of
90 * the description.
91 * @return The describe document of the artifact.
92 * @throws ArtifactDatabaseException Thrown id something went wrong
93 * during the creation of the describe document.
94 */
95 Document describe(String artifact, Document data, CallMeta callMeta)
96 throws ArtifactDatabaseException;
97
98 /**
99 * Advances the artifact identified by 'artifact' to the state
100 * 'target'. The result of the attempt is returned.
101 * @param artifact The identifier of the artifact.
102 * @param target The target state of the advance attempt.
103 * @param callMeta The meta information (language et. al.) of the
104 * advance attempt.
105 * @return The result document of the advance attempt.
106 * @throws ArtifactDatabaseException Thrown if something went wrong
107 * during the advance attempt.
108 */
109 Document advance(String artifact, Document target, CallMeta callMeta)
110 throws ArtifactDatabaseException;
111
112 /**
113 * Feeds the artifact identified by 'artifact' with some data 'data'.
114 * @param artifact The identifier of the artifact.
115 * @param data The data to be fed into the artifact.
116 * @param callMeta The meta information (language et. al.) of the feed
117 * attempt.
118 * @return The result of the feed attempt.
119 * @throws ArtifactDatabaseException Throw if something went wrong during
120 * the feed attempt.
121 */
122 Document feed(String artifact, Document data, CallMeta callMeta)
123 throws ArtifactDatabaseException;
124
125 /**
126 * Produces output for a given artifact identified by 'artifact' in
127 * a requested format 'format'. The writing of the data is done when
128 * the write() method of the returned DeferredOutput is called. This
129 * optimizes the out streaming of the data because the call can be
130 * deferred into to the calling context.
131 * @param artifact The identifier of the artifact.
132 * @param format The request format of the output.
133 * @param callMeta The meta information (language et. al.) of the output.
134 * @return The deferred output to be written later in the calling context.
135 * @throws ArtifactDatabaseException Thrown if something went wrong during
136 * producing the output.
137 */
138 DeferredOutput out(String artifact, Document format, CallMeta callMeta)
139 throws ArtifactDatabaseException;
140
141
142 /**
143 * Produces output for a given artifact identified by 'artifact' in
144 * a requested format 'format'. The writing of the data is done when
145 * the write() method of the returned DeferredOutput is called. This
146 * optimizes the out streaming of the data because the call can be
147 * deferred into to the calling context.
148 * @param artifact The identifier of the artifact.
149 * @param format The request format of the output.
150 * @param callMeta The meta information (language et. al.) of the output.
151 * @return The deferred output to be written later in the calling context.
152 * @throws ArtifactDatabaseException Thrown if something went wrong during
153 * producing the output.
154 */
155 DeferredOutput out(
156 String artifact,
157 String type,
158 Document format,
159 CallMeta callMeta)
160 throws ArtifactDatabaseException;
161
162 /**
163 * Produces an extenal represention of the artifact identified by
164 * 'artifact' to be re-imported by #importArtifact(Document, CallMeta)
165 * later.
166 * @param artifact The identifier of the artifact.
167 * @param callMeta The meta informatio (language et. al.) of the export.
168 * @return A extenal representation of the artifact.
169 * @throws ArtifactDatabaseException Thrown if something went wrong
170 * during export.
171 */
172 Document exportArtifact(String artifact, CallMeta callMeta)
173 throws ArtifactDatabaseException;
174
175 /**
176 * The symmetrical counter part of #exportArtifact(String, CallMeta).
177 * It attempts to import the artifact which is coded inside the 'data'
178 * document. When the import succeeds the new artifact is given a new
179 * internal identifier and the describe document of the artifact is
180 * returned.
181 * @param data The encoded artifact. Has to be the output of
182 * #exportArtifact(String, CallMeta).
183 * @param callMeta The meta information (language et. al.) of the
184 * import.
185 * @return The describe document of the imported artifact.
186 * @throws ArtifactDatabaseException Thrown if something went wrong during
187 * the import attempt.
188 */
189 Document importArtifact(Document data, CallMeta callMeta)
190 throws ArtifactDatabaseException;
191
192 /**
193 * Returns a list of services offered by this artifact database.
194 * @return The array returned contains tuples of (name, description)
195 * strings.
196 */
197 String [][] serviceNamesAndDescriptions();
198
199 /**
200 * Calls a service identified by 'service' with input document 'input'
201 * to produce some output document.
202 * @param service The name of the service.
203 * @param input The input document.
204 * @param callMeta The meta information (language et. al.) of the
205 * service call.
206 * @return The result document produced by the service.
207 * @throws ArtifactDatabaseException Thrown if someting went wrong during
208 * the service processing.
209 */
210 Service.Output process(String service, Document input, CallMeta callMeta)
211 throws ArtifactDatabaseException;
212
213 // User API
214
215 Document listUsers(CallMeta callMeta)
216 throws ArtifactDatabaseException;
217
218 Document findUser(Document data, CallMeta callMeta)
219 throws ArtifactDatabaseException;
220
221 Document createUser(Document data, CallMeta callMeta)
222 throws ArtifactDatabaseException;
223
224 Document deleteUser(String userId, CallMeta callMeta)
225 throws ArtifactDatabaseException;
226
227 // Collection API
228
229 Document getCollectionsMasterArtifact(String collectionId, CallMeta meta)
230 throws ArtifactDatabaseException;
231
232 Document listCollections(String userId, CallMeta callMeta)
233 throws ArtifactDatabaseException;
234
235 Document createCollection(String ownerId, Document data,
236 CallMeta callMeta)
237 throws ArtifactDatabaseException;
238
239 Document deleteCollection(String collectionId, CallMeta callMeta)
240 throws ArtifactDatabaseException;
241
242 Document describeCollection(String collectionId, CallMeta callMeta)
243 throws ArtifactDatabaseException;
244
245 Document getCollectionAttribute(String collectionId, CallMeta callMeta)
246 throws ArtifactDatabaseException;
247
248 Document setCollectionAttribute(
249 String collectionId,
250 CallMeta callMeta,
251 Document attribute)
252 throws ArtifactDatabaseException;
253
254 Document getCollectionItemAttribute(String collectionId, String artifactId,
255 CallMeta callMeta) throws ArtifactDatabaseException;
256
257 Document setCollectionItemAttribute(String collectionId, String artifactId,
258 Document attribute, CallMeta callMeta)
259 throws ArtifactDatabaseException;
260
261 Document addCollectionArtifact(String collectionId, String artifactId,
262 Document input, CallMeta callMeta) throws ArtifactDatabaseException;
263
264 Document removeCollectionArtifact(String collectionId, String artifactId,
265 CallMeta callMeta) throws ArtifactDatabaseException;
266
267 Document listCollectionArtifacts(String collectionId,
268 CallMeta callMeta) throws ArtifactDatabaseException;
269
270 DeferredOutput outCollection(String collectionId,
271 Document format, CallMeta callMeta)
272 throws ArtifactDatabaseException;
273
274 DeferredOutput outCollection(String collectionId, String type,
275 Document format, CallMeta callMeta)
276 throws ArtifactDatabaseException;
277
278 Document setCollectionTTL(String collectionId, Document doc, CallMeta meta)
279 throws ArtifactDatabaseException;
280
281 Document setCollectionName(String collectionId, Document doc, CallMeta meta)
282 throws ArtifactDatabaseException;
283
284 public interface ArtifactLoadedCallback {
285 void artifactLoaded(
286 String userId,
287 String collectionId,
288 String collectionName,
289 Date collectionCreated,
290 String artifactId,
291 Date artifactCreated,
292 Artifact artifact);
293 };
294
295 public void loadAllArtifacts(ArtifactLoadedCallback callback)
296 throws ArtifactDatabaseException;
297 }
298 // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :
http://dive4elements.wald.intevation.org