PackageAdministration


1   package org.enhydra.shark.api.client.wfservice;
2   
3   import org.enhydra.shark.api.client.wfbase.BaseException;
4   import org.enhydra.shark.api.RepositoryTransaction;
5   
6   
7   /**
8    * Interface used to perform some administrative operations related
9    * to packages (XPDLs).
10   * @author Sasa Bojanic
11   * @author Vladimir Puskas
12   */
13  public interface PackageAdministration {
14  
15     /**
16      * This method is used to let shark know who uses this API.
17      *
18      * @param    userId              String representing user Id.
19      *
20      */
21     void connect (String   userId);
22  
23     /**
24      * Returns an array of strings representing Ids of packages that are
25      * loaded into engine.
26      *
27      * @return Array of package Ids that are loaded into engine.
28      * @throws BaseException If something unexpected happens.
29      *
30      */
31     String  [] getOpenedPackageIds () throws BaseException;
32  
33     /**
34      * Returns an array of strings representing Ids of packages that are
35      * loaded into engine.
36      *
37      * @param  t RepositoryTransaction.
38      * @return Array of package Ids that are loaded into engine.
39      * @throws   BaseException If something unexpected happens.
40      *
41      */
42     String  [] getOpenedPackageIds (RepositoryTransaction t) throws BaseException;
43  
44     /**
45      * Returns an array of strings representing versions of package with given Id that are
46      * loaded into engine.
47      *
48      * @return Array of versions of package with given Id that are loaded into engine.
49      * @throws BaseException If something unexpected happens.
50      *
51      */
52     String  [] getPackageVersions (String   pkgId) throws BaseException;
53  
54     /**
55      * Returns an array of strings representing versions of package with given Id that are
56      * loaded into engine.
57      *
58      * @param  t RepositoryTransaction.
59      * @return Array of versions of package with given Id that are loaded into engine.
60      * @throws   BaseException If something unexpected happens.
61      *
62      */
63     String  [] getPackageVersions (RepositoryTransaction t,String   pkgId) throws BaseException;
64  
65     /**
66      * Returns true if package with the given Id is loaded into engine.
67      *
68      * @param    pkgId  Id of package to be tested if it is loaded into engine.
69      * @return true if package with the given Id is loaded into engine, otherwuse
70      * false.
71      * @throws   BaseException If something unexpected happens.
72      *
73      */
74     boolean isPackageOpened (String   pkgId)  throws BaseException;
75  
76     /**
77      * Returns true if package with the given Id is loaded into engine.
78      *
79      * @param    t  RepositoryTransaction.
80      * @param    pkgId  Id of package to be tested if it is loaded into engine.
81      * @return true if package with the given Id is loaded into engine, otherwuse
82      * false.
83      * @throws   BaseException If something unexpected happens.
84      *
85      */
86     boolean isPackageOpened (RepositoryTransaction t,String   pkgId)  throws BaseException;
87  
88     /**
89      * Returns the content of XPDL file containing package definition with the
90      * given Id as an array of bytes. The package has to be loaded into shark
91      * engine (it is the XPDL file from engine's internal repository).
92      *
93      * @param    pkgId  Id of package which XPDL file content has to be returned.
94      * @return   Content of XPDL file.
95      * @throws   BaseException If something unexpected happens.
96      *
97      */
98     byte[] getPackageContent (String   pkgId) throws BaseException;
99  
100    /**
101     * Returns the content of XPDL file containing package definition with the
102     * given Id as an array of bytes. The package has to be loaded into shark
103     * engine (it is the XPDL file from engine's internal repository).
104     *
105     * @param    t RepositoryTransaction.
106     * @param    pkgId  Id of package which XPDL file content has to be returned.
107     * @return   Content of XPDL file.
108     * @throws   BaseException If something unexpected happens.
109     *
110     */
111    byte[] getPackageContent (RepositoryTransaction t,String   pkgId) throws BaseException;
112 
113    /**
114     * Returns the content of XPDL file containing package definition with the
115     * given Id as an array of bytes. The package has to be loaded into shark
116     * engine (it is the XPDL file from engine's internal repository).
117     * <p> The method returns the content of the current version of XPDL.
118     *
119     * @param    pkgId  Id of package which XPDL file content has to be returned.
120     * @param    pkgVer The version of package which XPDL file content has to be returned.
121     * @return   Content of XPDL file.
122     * @throws   BaseException If something unexpected happens.
123     *
124     */
125    byte[] getPackageContent (String   pkgId,String   pkgVer) throws BaseException;
126 
127    /**
128     * Returns the content of XPDL file containing package definition with the
129     * given Id as an array of bytes. The package has to be loaded into shark
130     * engine (it is the XPDL file from engine's internal repository).
131     *
132     * @param    t RepositoryTransaction.
133     * @param    pkgId  Id of package which XPDL file content has to be returned.
134     * @param    pkgVer The version of package which XPDL file content has to be returned.
135     * @return   Content of XPDL file.
136     * @throws   BaseException If something unexpected happens.
137     *
138     */
139    byte[] getPackageContent (RepositoryTransaction t,String   pkgId,String   pkgVer) throws BaseException;
140 
141    /**
142     * Returns the current version of the package.
143     *
144     * @param    pkgId  Id of package which current version we want to know.
145     *
146     * @return   the current package version
147     *
148     * @throws   BaseException If something unexpected happens.
149     *
150     */
151    String   getCurrentPackageVersion (String   pkgId) throws BaseException;
152 
153    /**
154     * Returns the current version of the package.
155     *
156     * @param    t RepositoryTransaction.
157     * @param    pkgId  Id of package which current version we want to know.
158     *
159     * @return   the current package version
160     *
161     * @throws   BaseException If something unexpected happens.
162     *
163     */
164    String   getCurrentPackageVersion (RepositoryTransaction t,String   pkgId) throws BaseException;
165 
166    /**
167     * Allows administrator to load a package that is defined in XPDL file which
168     * path (relative to the external repository folder) is given as a parameter.
169     * After the package is loaded into shark engine, the processes can be
170     * instantiated from process definitions that are contained within the package.
171     *
172     * @param    relativePath  path of package XPDL file relative to the
173     * external repository folder.
174     * @return   The id of package that is going to be opened.
175     *
176     * @throws   BaseException If something unexpected happens.
177     * @throws   PackageInvalid If package that user wants to open hadn't passed
178     * shark's validation process.
179     * @throws   ExternalPackageInvalid If package that user wants to open has
180     * a external package, and this external package hadn't passed shark's
181     * validation.
182     *
183     */
184    String   openPackage (String   relativePath) throws BaseException, PackageInvalid, ExternalPackageInvalid;
185 
186    /**
187     * Allows administrator to load a package that is defined in XPDL file which
188     * path (relative to the external repository folder) is given as a parameter.
189     * After the package is loaded into shark engine, the processes can be
190     * instantiated from process definitions that are contained within the package.
191     *
192     * @param    t  RepositoryTransaction.
193     * @param    relativePath  path of package XPDL file relative to the
194     * external repository folder.
195     * @return   The id of package that is going to be opened.
196     *
197     * @throws   BaseException If something unexpected happens.
198     * @throws   PackageInvalid If package that user wants to open hadn't passed
199     * shark's validation process.
200     * @throws   ExternalPackageInvalid If package that user wants to open has
201     * a external package, and this external package hadn't passed shark's
202     * validation.
203     *
204     */
205    String   openPackage (RepositoryTransaction t,String   relativePath) throws BaseException, PackageInvalid, ExternalPackageInvalid;
206 
207    /**
208     * Allows administrator to update a package that is loaded into shark and has
209     * the given id, with the package that can be found in XPDL file that is placed
210     * at given path (relative to shark's external repository). After successfull
211     * update, every process that has already been instantiated from the process
212     * definitions contained within the package will continue its execution
213     * based on old definition, but one can instantiate processes based on
214     * new (updated) process definition.
215     *
216     * @param    id  The id of package that is loaded into engine,
217     * and has to be updated.
218     * @param    relativePathToNewPackage  path of XPDL file containing the
219     * package that we want to update package with (path is relative to
220     * shark's external repository).
221     *
222     * @throws   BaseException If something unexpected happens.
223     * @throws   PackageUpdateNotAllowed If package update is currently not
224     * allowed
225     * @throws   PackageInvalid If package that user wants to open hadn't passed
226     * shark's validation process.
227     * @throws   ExternalPackageInvalid If package that user wants to open has
228     * an external package, and this external package hadn't passed shark's
229     * validation.
230     *
231     */
232    void updatePackage (String   id, String   relativePathToNewPackage) throws BaseException, PackageUpdateNotAllowed, PackageInvalid, ExternalPackageInvalid;
233 
234    /**
235     * Allows administrator to update a package that is loaded into shark and has
236     * the given id, with the package that can be found in XPDL file that is placed
237     * at given path (relative to shark's external repository). After successfull
238     * update, every process that has already been instantiated from the process
239     * definitions contained within the package will continue its execution
240     * based on old definition, but one can instantiate processes based on
241     * new (updated) process definition.
242     *
243     * @param    t  RepositoryTransaction.
244     * @param    id  The id of package that is loaded into engine,
245     * and has to be updated.
246     * @param    relativePathToNewPackage  path of XPDL file containing the
247     * package that we want to update package with (path is relative to
248     * shark's external repository).
249     *
250     * @throws   BaseException If something unexpected happens.
251     * @throws   PackageUpdateNotAllowed If package update is currently not
252     * allowed
253     * @throws   PackageInvalid If package that user wants to open hadn't passed
254     * shark's validation process.
255     * @throws   ExternalPackageInvalid If package that user wants to open has
256     * an external package, and this external package hadn't passed shark's
257     * validation.
258     *
259     */
260    void updatePackage (RepositoryTransaction t,String   id, String   relativePathToNewPackage) throws BaseException, PackageUpdateNotAllowed, PackageInvalid, ExternalPackageInvalid;
261 
262    /**
263     * Allows administrator to unload all package versions with the given id from shark.
264     * After successfull unload, there will no longer be possible to
265     * instantiate processes from definitions that were contained within
266     * that package.
267     *
268     * @param    id  The id of package that is loaded into engine,
269     * and has to be closed.
270     * @throws   BaseException If something unexpected happens.
271     * @throws   PackageInUse If this package is used by any other package that
272     * references it as an external package, and is also loaded into engine.
273     * @throws   PackageHasActiveProcesses If there are processes written in
274     * instance persistence repository, that are instantiated from process definitions
275     * contained within package we want to unload.
276     *
277     */
278    void closePackage (String   id) throws BaseException, PackageInUse, PackageHasActiveProcesses;
279 
280    /**
281     * Allows administrator to unload all package versions with the given id from shark.
282     * After successfull unload, there will no longer be possible to
283     * instantiate processes from definitions that were contained within
284     * that package.
285     *
286     * @param    t RepositoryTransaction.
287     * @param    id  The id of package that is loaded into engine,
288     * and has to be closed.
289     * @throws   BaseException If something unexpected happens.
290     * @throws   PackageInUse If this package is used by any other package that
291     * references it as an external package, and is also loaded into engine.
292     * @throws   PackageHasActiveProcesses If there are processes written in
293     * instance persistence repository, that are instantiated from process definitions
294     * contained within package we want to unload.
295     *
296     */
297    void closePackage (RepositoryTransaction t,String   id) throws BaseException, PackageInUse, PackageHasActiveProcesses;
298 
299    /**
300     * Allows administrator to unload the package with the given id and given version from shark.
301     * After successfull unload, there will no longer be possible to
302     * instantiate processes from definitions that were contained within
303     * that package.
304     *
305     * @param    id  The id of package that is loaded into engine,
306     * and has to be closed.
307     * @throws   BaseException If something unexpected happens.
308     * @throws   PackageInUse If this package is used by any other package that
309     * references it as an external package, and is also loaded into engine.
310     * @throws   PackageHasActiveProcesses If there are processes written in
311     * instance persistence repository, that are instantiated from process definitions
312     * contained within package we want to unload.
313     *
314     */
315    void closePackage (String   id,String   ver) throws BaseException, PackageInUse, PackageHasActiveProcesses;
316 
317    /**
318     * Allows administrator to unload the package with the given id and given version from shark.
319     * After successfull unload, there will no longer be possible to
320     * instantiate processes from definitions that were contained within
321     * that package.
322     *
323     * @param    t RepositoryTransaction.
324     * @param    id  The id of package that is loaded into engine,
325     * and has to be closed.
326     * @throws   BaseException If something unexpected happens.
327     * @throws   PackageInUse If this package is used by any other package that
328     * references it as an external package, and is also loaded into engine.
329     * @throws   PackageHasActiveProcesses If there are active processes
330     * that are instantiated from process definitions contained within package
331     * we want to unload.
332     *
333     */
334    void closePackage (RepositoryTransaction t,String   id,String   ver) throws BaseException, PackageInUse, PackageHasActiveProcesses;
335 
336    /**
337     * Returns information if the current version of package with given id, that
338     * is loaded into engine, is referenced from other package (as an external package)
339     * that is also loaded into engine.
340     *
341     * @param    pkgId The Id of package we want to check if it is referenced.
342     * @return   true if package is referenced from other package, otherwise
343     * false.
344     * @throws   BaseException If something unexpected happens.
345     *
346     */
347    boolean isPackageReferenced (String   pkgId) throws BaseException;
348 
349    /**
350     * Returns information if the current version of package with given id, that
351     * is loaded into engine, is referenced from other package (as an external package)
352     * that is also loaded into engine.
353     *
354     * @param    t RepositoryTransaction.
355     * @param    pkgId The Id of package we want to check if it is referenced.
356     * @return   true if package is referenced from other package, otherwise
357     * false.
358     * @throws   BaseException If something unexpected happens.
359     *
360     */
361    boolean isPackageReferenced (RepositoryTransaction t,String   pkgId) throws BaseException;
362 
363    /**
364     * Synchronizes XPDL caches with the repository state. It is supposed to be
365     * used in scenario when there are several VMs using shark, and when one of
366     * them loads new XPDL or updates existing.
367     *<p> It checks for all XPDLs in repository, and compares it against the cached
368     * ones, and determines which cached instances should be removed from cache
369     * permanently, which new instances should be loaded, and which old instances
370     * should be reloaded (because the change of their external package instance).
371     *
372     * @throws   BaseException If something unexpected happens.
373     *
374     */
375    void synchronizeXPDLCache () throws BaseException;
376 
377    /**
378     * Synchronizes XPDL caches with the repository state. It is supposed to be
379     * used in scenario when there are several VMs using shark, and when one of
380     * them loads new XPDL or updates existing.
381     *<p> It checks for all XPDLs in repository, and compares it against the cached
382     * ones, and determines which cached instances should be removed from cache
383     * permanently, which new instances should be loaded, and which old instances
384     * should be reloaded (because the change of their external package instance).
385     *
386     * @param    t RepositoryTransaction.
387     * @throws   BaseException If something unexpected happens.
388     *
389     */
390    void synchronizeXPDLCache (RepositoryTransaction t) throws BaseException;
391 
392    /**
393     * Clears XPDL caches. After clearing caches, first time some XPDL
394     * instance is required, the cache is being filled with all instances
395     * that exist in DB.
396     *
397     * @throws   BaseException If something unexpected happens.
398     *
399     */
400    void clearXPDLCache () throws BaseException;
401 
402    /**
403     * Clears XPDL caches. After clearing caches, first time some XPDL
404     * instance is required, the cache is being filled with all instances
405     * that exist in DB.
406     *
407     * @param    t RepositoryTransaction.
408     * @throws   BaseException If something unexpected happens.
409     *
410     */
411    void clearXPDLCache (RepositoryTransaction t) throws BaseException;
412 
413    /**
414     * Synchronizes XPDL caches with the repository state. It is supposed to be
415     * used in scenario when there are several VMs using shark, and when one of
416     * them loads new XPDL or updates existing.
417     *<p> It first clears all instances from the cache, and then checks for all
418     * XPDLs in repository, and loads them into cache.
419     * <p><b>Note: for better performance, use #synchronizeXPDLCache method.
420     *
421     * @throws   BaseException If something unexpected happens.
422     *
423     */
424    void refreshXPDLCache () throws BaseException;
425 
426    /**
427     * Synchronizes XPDL caches with the repository state. It is supposed to be
428     * used in scenario when there are several VMs using shark, and when one of
429     * them loads new XPDL or updates existing.
430     * <p> It first clears all instances from the cache, and then checks for all
431     * XPDLs in repository, and loads them into cache.
432     * <p><b>Note: for better performance, use #synchronizeXPDLCache method.
433     *
434     * @throws   BaseException If something unexpected happens.
435     *
436     */
437    void refreshXPDLCache (RepositoryTransaction t) throws BaseException;
438 }
439
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags