001: package org.enhydra.shark.api.client.wfservice;
002:
003: import org.enhydra.shark.api.client.wfmc.wapi.WMSessionHandle;
004:
005: /**
006: * Interface used to perform some administrative operations related to packages (XPDLs).
007: *
008: * @author Sasa Bojanic
009: * @author Vladimir Puskas
010: */
011: public interface PackageAdministration {
012:
013: /**
014: * Returns an array of strings representing Ids of packages that are loaded into
015: * engine.
016: *
017: * @return Array of package Ids that are loaded into engine.
018: * @throws Exception If something unexpected happens.
019: */
020: String[] getOpenedPackageIds(WMSessionHandle shandle)
021: throws Exception;
022:
023: /**
024: * Returns an array of strings representing versions of package with given Id that are
025: * loaded into engine.
026: *
027: * @return Array of versions of package with given Id that are loaded into engine.
028: * @throws Exception If something unexpected happens.
029: */
030: String[] getPackageVersions(WMSessionHandle shandle, String pkgId)
031: throws Exception;
032:
033: /**
034: * Returns true if package with the given Id is loaded into engine.
035: *
036: * @param pkgId Id of package to be tested if it is loaded into engine.
037: * @return true if package with the given Id is loaded into engine, otherwuse false.
038: * @throws Exception If something unexpected happens.
039: */
040: boolean isPackageOpened(WMSessionHandle shandle, String pkgId)
041: throws Exception;
042:
043: /**
044: * Returns the content of XPDL file containing package definition with the given Id and
045: * version as an array of bytes. The package has to be loaded into shark engine.
046: * <p>
047: * If version parameter is an empty string or null, method returns the content of the
048: * current version of XPDL.
049: *
050: * @param pkgId Id of package which XPDL file content has to be returned.
051: * @param pkgVer The version of package which XPDL file content has to be returned.
052: * @return Content of XPDL file.
053: * @throws Exception If something unexpected happens.
054: */
055: byte[] getPackageContent(WMSessionHandle shandle, String pkgId,
056: String pkgVer) throws Exception;
057:
058: /**
059: * Returns the WMEntity representing package definition with the given Id and version.
060: * The package has to be loaded into shark engine.
061: * <p>
062: * If version parameter is an empty string or null, method returns the content of the
063: * current version of XPDL.
064: *
065: * @param pkgId Id of package which XPDL file content has to be returned.
066: * @param pkgVer The version of package which XPDL file content has to be returned.
067: * @return WMEntity representing XPDL file.
068: * @throws Exception If something unexpected happens.
069: */
070: WMEntity getPackageEntity(WMSessionHandle shandle, String pkgId,
071: String pkgVer) throws Exception;
072:
073: /**
074: * Returns the current version of the package.
075: *
076: * @param pkgId Id of package which current version we want to know.
077: * @return the current package version
078: * @throws Exception If something unexpected happens.
079: */
080: String getCurrentPackageVersion(WMSessionHandle shandle,
081: String pkgId) throws Exception;
082:
083: /**
084: * Allows administrator to load a package that is defined as byte[] representation of
085: * Package's XPDL schema. After the package is loaded into shark engine, the processes
086: * can be instantiated from process definitions that are contained within the package.
087: *
088: * @param schemaContent byte[] representation of the Package's XPDL schema
089: * @return The id of package that is going to be opened.
090: * @throws Exception If something unexpected happens. PackageInvalid exception is
091: * thrown if package that user wants to open hadn't passed shark's
092: * validation process and ExternalPackageInvalid is thrown if package that
093: * user wants to open has a external package, and this external package
094: * hadn't passed shark's validation.
095: */
096: WMEntity uploadPackage(WMSessionHandle shandle, byte[] schemaContent)
097: throws Exception;
098:
099: /**
100: * Allows administrator to load a packages that are defined as byte[] representation of
101: * Packages' XPDL schemas. After the package is loaded into shark engine, the processes
102: * can be instantiated from process definitions that are contained within the package.
103: *
104: * @param schemaContents List of byte[] representation of the Packages' XPDL schemas
105: * @return The id of the main package that is going to be opened.
106: * @throws Exception If something unexpected happens. PackageInvalid exception is
107: * thrown if package that user wants to open hadn't passed shark's
108: * validation process and ExternalPackageInvalid is thrown if package that
109: * user wants to open has a external package, and this external package
110: * hadn't passed shark's validation.
111: */
112: WMEntity uploadPackages(WMSessionHandle shandle,
113: byte[][] schemaContents) throws Exception;
114:
115: /**
116: * Allows administrator to load a package that is defined in XPDL file which path is
117: * given as a parameter. After the package is loaded into shark engine, the processes
118: * can be instantiated from process definitions that are contained within the package.
119: *
120: * @param absolutePath path of package XPDL file to open
121: * @return The id of package that is going to be opened.
122: * @throws Exception If something unexpected happens. PackageInvalid exception is
123: * thrown if package that user wants to open hadn't passed shark's
124: * validation process and ExternalPackageInvalid is thrown if package that
125: * user wants to open has a external package, and this external package
126: * hadn't passed shark's validation.
127: */
128: WMEntity openPackage(WMSessionHandle shandle, String absolutePath)
129: throws Exception;
130:
131: /**
132: * Allows administrator to update a package that is loaded into shark and has the given
133: * id, with the package which XPDL representation is provided as a given byte[]. After
134: * successful update, every process that has already been instantiated from the process
135: * definitions contained within the package will continue its execution based on old
136: * definition, but one can instantiate processes based on new (updated) process
137: * definition.
138: *
139: * @param id The id of package that is loaded into engine, and has to be updated.
140: * @param schemaContent byte[] representation of XPDL schema defining a Package
141: * @throws Exception If something unexpected happens. PackageUpdateNotAllowed is thrown
142: * if package update is currently not allowed, PackageInvalid exception is
143: * thrown if package that user wants to open hadn't passed shark's
144: * validation process and ExternalPackageInvalid is thrown if package that
145: * user wants to open has a external package, and this external package
146: * hadn't passed shark's validation.
147: */
148: WMEntity updatePackage(WMSessionHandle shandle, String id,
149: byte[] schemaContent) throws Exception;
150:
151: /**
152: * Allows administrator to update a package that is loaded into shark and has the given
153: * id, with the package that can be found in XPDL file that is placed at given path.
154: * After successful update, every process that has already been instantiated from the
155: * process definitions contained within the package will continue its execution based
156: * on old definition, but one can instantiate processes based on new (updated) process
157: * definition.
158: *
159: * @param id The id of package that is loaded into engine, and has to be updated.
160: * @param absolutePathToNewPackage path of XPDL file containing the 'updater' package
161: * @throws Exception If something unexpected happens. PackageUpdateNotAllowed is thrown
162: * if package update is currently not allowed, PackageInvalid exception is
163: * thrown if package that user wants to open hadn't passed shark's
164: * validation process and ExternalPackageInvalid is thrown if package that
165: * user wants to open has a external package, and this external package
166: * hadn't passed shark's validation.
167: */
168: WMEntity updatePackageFromFile(WMSessionHandle shandle, String id,
169: String absolutePathToNewPackage) throws Exception;
170:
171: /**
172: * Allows administrator to unload all package versions with the given id from shark.
173: * After successful unload, there will no longer be possible to instantiate processes
174: * from definitions that were contained within that package.
175: *
176: * @param id The id of package that is loaded into engine, and has to be closed.
177: * @throws Exception If something unexpected happens. PackageInUse exception is thrown
178: * if this package is used by any other package that references it as an
179: * external package, and is also loaded into engine,
180: * PackageHasActiveProcesses is thrown if there are processes written in
181: * instance persistence repository, that are instantiated from process
182: * definitions contained within package we want to unload.
183: */
184: WMEntityIterator closeAllPackagesForId(WMSessionHandle shandle,
185: String id) throws Exception;
186:
187: /**
188: * Allows administrator to unload the package with the given id and given version from
189: * shark. After successful unload, there will no longer be possible to instantiate
190: * processes from definitions that were contained within that package.
191: * <p>
192: * If version parameter is an empty string or null, all the versions for the given id
193: * will be unloaded if possible (otherwise, exception will be thrown).
194: *
195: * @param id The id of package that is loaded into engine, and has to be closed.
196: * @throws Exception If something unexpected happens. PackageInUse exception is thrown
197: * if this package is used by any other package that references it as an
198: * external package, and is also loaded into engine,
199: * PackageHasActiveProcesses is thrown if there are processes written in
200: * instance persistence repository, that are instantiated from process
201: * definitions contained within package we want to unload.
202: */
203: WMEntity closePackage(WMSessionHandle shandle, String id, String ver)
204: throws Exception;
205:
206: /**
207: * Returns information if the current version of package with given id, that is loaded
208: * into engine, is referenced from other package (as an external package) that is also
209: * loaded into engine.
210: *
211: * @param pkgId The Id of package we want to check if it is referenced.
212: * @return true if package is referenced from other package, otherwise false.
213: * @throws Exception If something unexpected happens.
214: */
215: boolean isPackageReferenced(WMSessionHandle shandle, String pkgId)
216: throws Exception;
217:
218: /**
219: * Synchronizes XPDL caches with the repository state. It is supposed to be used in
220: * scenario when there are several VMs using shark, and when one of them loads new XPDL
221: * or updates existing.
222: * <p>
223: * It checks for all XPDLs in repository, and compares it against the cached ones, and
224: * determines which cached instances should be removed from cache permanently, which
225: * new instances should be loaded, and which old instances should be reloaded (because
226: * the change of their external package instance).
227: *
228: * @throws Exception If something unexpected happens.
229: */
230: void synchronizeXPDLCache(WMSessionHandle shandle) throws Exception;
231:
232: /**
233: * Clears XPDL caches. After clearing caches, first time some XPDL instance is
234: * required, the cache is being filled with all instances that exist in DB.
235: *
236: * @throws Exception If something unexpected happens.
237: */
238: void clearXPDLCache(WMSessionHandle shandle) throws Exception;
239:
240: /**
241: * Synchronizes XPDL caches with the repository state. It is supposed to be used in
242: * scenario when there are several VMs using shark, and when one of them loads new XPDL
243: * or updates existing.
244: * <p>
245: * It first clears all instances from the cache, and then checks for all XPDLs in
246: * repository, and loads them into cache.
247: * <p>
248: * <b>Note: for better performance, use #synchronizeXPDLCache method.
249: *
250: * @throws Exception If something unexpected happens.
251: */
252: void refreshXPDLCache(WMSessionHandle shandle) throws Exception;
253: }
|