org.enhydra.shark.api.client.wfservice
Interface PackageAdministration


public interface PackageAdministration

Interface used to perform some administrative operations related to packages (XPDLs).

Author:
Sasa Bojanic, Vladimir Puskas

Method Summary
 void clearXPDLCache(WMSessionHandle shandle)
          Clears XPDL caches.
 WMEntityIterator closeAllPackagesForId(WMSessionHandle shandle, java.lang.String id)
          Allows administrator to unload all package versions with the given id from shark.
 WMEntity closePackage(WMSessionHandle shandle, java.lang.String id, java.lang.String ver)
          Allows administrator to unload the package with the given id and given version from shark.
 java.lang.String getCurrentPackageVersion(WMSessionHandle shandle, java.lang.String pkgId)
          Returns the current version of the package.
 java.lang.String[] getOpenedPackageIds(WMSessionHandle shandle)
          Returns an array of strings representing Ids of packages that are loaded into engine.
 byte[] getPackageContent(WMSessionHandle shandle, java.lang.String pkgId, java.lang.String pkgVer)
          Returns the content of XPDL file containing package definition with the given Id and version as an array of bytes.
 WMEntity getPackageEntity(WMSessionHandle shandle, java.lang.String pkgId, java.lang.String pkgVer)
          Returns the WMEntity representing package definition with the given Id and version.
 java.lang.String[] getPackageVersions(WMSessionHandle shandle, java.lang.String pkgId)
          Returns an array of strings representing versions of package with given Id that are loaded into engine.
 boolean isPackageOpened(WMSessionHandle shandle, java.lang.String pkgId)
          Returns true if package with the given Id is loaded into engine.
 boolean isPackageReferenced(WMSessionHandle shandle, java.lang.String pkgId)
          Returns information if the current version of package with given id, that is loaded into engine, is referenced from other package (as an external package) that is also loaded into engine.
 WMEntity openPackage(WMSessionHandle shandle, java.lang.String absolutePath)
          Allows administrator to load a package that is defined in XPDL file which path is given as a parameter.
 void refreshXPDLCache(WMSessionHandle shandle)
          Synchronizes XPDL caches with the repository state.
 void synchronizeXPDLCache(WMSessionHandle shandle)
          Synchronizes XPDL caches with the repository state.
 WMEntity updatePackage(WMSessionHandle shandle, java.lang.String id, byte[] schemaContent)
          Allows administrator to update a package that is loaded into shark and has the given id, with the package which XPDL representation is provided as a given byte[].
 WMEntity updatePackageFromFile(WMSessionHandle shandle, java.lang.String id, java.lang.String absolutePathToNewPackage)
          Allows administrator to update a package that is loaded into shark and has the given id, with the package that can be found in XPDL file that is placed at given path.
 WMEntity uploadPackage(WMSessionHandle shandle, byte[] schemaContent)
          Allows administrator to load a package that is defined as byte[] representation of Package's XPDL schema.
 WMEntity uploadPackages(WMSessionHandle shandle, byte[][] schemaContents)
          Allows administrator to load a packages that are defined as byte[] representation of Packages' XPDL schemas.
 

Method Detail

getOpenedPackageIds

java.lang.String[] getOpenedPackageIds(WMSessionHandle shandle)
                                       throws java.lang.Exception
Returns an array of strings representing Ids of packages that are loaded into engine.

Returns:
Array of package Ids that are loaded into engine.
Throws:
java.lang.Exception - If something unexpected happens.

getPackageVersions

java.lang.String[] getPackageVersions(WMSessionHandle shandle,
                                      java.lang.String pkgId)
                                      throws java.lang.Exception
Returns an array of strings representing versions of package with given Id that are loaded into engine.

Returns:
Array of versions of package with given Id that are loaded into engine.
Throws:
java.lang.Exception - If something unexpected happens.

isPackageOpened

boolean isPackageOpened(WMSessionHandle shandle,
                        java.lang.String pkgId)
                        throws java.lang.Exception
Returns true if package with the given Id is loaded into engine.

Parameters:
pkgId - Id of package to be tested if it is loaded into engine.
Returns:
true if package with the given Id is loaded into engine, otherwuse false.
Throws:
java.lang.Exception - If something unexpected happens.

getPackageContent

byte[] getPackageContent(WMSessionHandle shandle,
                         java.lang.String pkgId,
                         java.lang.String pkgVer)
                         throws java.lang.Exception
Returns the content of XPDL file containing package definition with the given Id and version as an array of bytes. The package has to be loaded into shark engine.

If version parameter is an empty string or null, method returns the content of the current version of XPDL.

Parameters:
pkgId - Id of package which XPDL file content has to be returned.
pkgVer - The version of package which XPDL file content has to be returned.
Returns:
Content of XPDL file.
Throws:
java.lang.Exception - If something unexpected happens.

getPackageEntity

WMEntity getPackageEntity(WMSessionHandle shandle,
                          java.lang.String pkgId,
                          java.lang.String pkgVer)
                          throws java.lang.Exception
Returns the WMEntity representing package definition with the given Id and version. The package has to be loaded into shark engine.

If version parameter is an empty string or null, method returns the content of the current version of XPDL.

Parameters:
pkgId - Id of package which XPDL file content has to be returned.
pkgVer - The version of package which XPDL file content has to be returned.
Returns:
WMEntity representing XPDL file.
Throws:
java.lang.Exception - If something unexpected happens.

getCurrentPackageVersion

java.lang.String getCurrentPackageVersion(WMSessionHandle shandle,
                                          java.lang.String pkgId)
                                          throws java.lang.Exception
Returns the current version of the package.

Parameters:
pkgId - Id of package which current version we want to know.
Returns:
the current package version
Throws:
java.lang.Exception - If something unexpected happens.

uploadPackage

WMEntity uploadPackage(WMSessionHandle shandle,
                       byte[] schemaContent)
                       throws java.lang.Exception
Allows administrator to load a package that is defined as byte[] representation of Package's XPDL schema. After the package is loaded into shark engine, the processes can be instantiated from process definitions that are contained within the package.

Parameters:
schemaContent - byte[] representation of the Package's XPDL schema
Returns:
The id of package that is going to be opened.
Throws:
java.lang.Exception - If something unexpected happens. PackageInvalid exception is thrown if package that user wants to open hadn't passed shark's validation process and ExternalPackageInvalid is thrown if package that user wants to open has a external package, and this external package hadn't passed shark's validation.

uploadPackages

WMEntity uploadPackages(WMSessionHandle shandle,
                        byte[][] schemaContents)
                        throws java.lang.Exception
Allows administrator to load a packages that are defined as byte[] representation of Packages' XPDL schemas. After the package is loaded into shark engine, the processes can be instantiated from process definitions that are contained within the package.

Parameters:
schemaContents - List of byte[] representation of the Packages' XPDL schemas
Returns:
The id of the main package that is going to be opened.
Throws:
java.lang.Exception - If something unexpected happens. PackageInvalid exception is thrown if package that user wants to open hadn't passed shark's validation process and ExternalPackageInvalid is thrown if package that user wants to open has a external package, and this external package hadn't passed shark's validation.

openPackage

WMEntity openPackage(WMSessionHandle shandle,
                     java.lang.String absolutePath)
                     throws java.lang.Exception
Allows administrator to load a package that is defined in XPDL file which path is given as a parameter. After the package is loaded into shark engine, the processes can be instantiated from process definitions that are contained within the package.

Parameters:
absolutePath - path of package XPDL file to open
Returns:
The id of package that is going to be opened.
Throws:
java.lang.Exception - If something unexpected happens. PackageInvalid exception is thrown if package that user wants to open hadn't passed shark's validation process and ExternalPackageInvalid is thrown if package that user wants to open has a external package, and this external package hadn't passed shark's validation.

updatePackage

WMEntity updatePackage(WMSessionHandle shandle,
                       java.lang.String id,
                       byte[] schemaContent)
                       throws java.lang.Exception
Allows administrator to update a package that is loaded into shark and has the given id, with the package which XPDL representation is provided as a given byte[]. After successful update, every process that has already been instantiated from the process definitions contained within the package will continue its execution based on old definition, but one can instantiate processes based on new (updated) process definition.

Parameters:
id - The id of package that is loaded into engine, and has to be updated.
schemaContent - byte[] representation of XPDL schema defining a Package
Throws:
java.lang.Exception - If something unexpected happens. PackageUpdateNotAllowed is thrown if package update is currently not allowed, PackageInvalid exception is thrown if package that user wants to open hadn't passed shark's validation process and ExternalPackageInvalid is thrown if package that user wants to open has a external package, and this external package hadn't passed shark's validation.

updatePackageFromFile

WMEntity updatePackageFromFile(WMSessionHandle shandle,
                               java.lang.String id,
                               java.lang.String absolutePathToNewPackage)
                               throws java.lang.Exception
Allows administrator to update a package that is loaded into shark and has the given id, with the package that can be found in XPDL file that is placed at given path. After successful update, every process that has already been instantiated from the process definitions contained within the package will continue its execution based on old definition, but one can instantiate processes based on new (updated) process definition.

Parameters:
id - The id of package that is loaded into engine, and has to be updated.
absolutePathToNewPackage - path of XPDL file containing the 'updater' package
Throws:
java.lang.Exception - If something unexpected happens. PackageUpdateNotAllowed is thrown if package update is currently not allowed, PackageInvalid exception is thrown if package that user wants to open hadn't passed shark's validation process and ExternalPackageInvalid is thrown if package that user wants to open has a external package, and this external package hadn't passed shark's validation.

closeAllPackagesForId

WMEntityIterator closeAllPackagesForId(WMSessionHandle shandle,
                                       java.lang.String id)
                                       throws java.lang.Exception
Allows administrator to unload all package versions with the given id from shark. After successful unload, there will no longer be possible to instantiate processes from definitions that were contained within that package.

Parameters:
id - The id of package that is loaded into engine, and has to be closed.
Throws:
java.lang.Exception - If something unexpected happens. PackageInUse exception is thrown if this package is used by any other package that references it as an external package, and is also loaded into engine, PackageHasActiveProcesses is thrown if there are processes written in instance persistence repository, that are instantiated from process definitions contained within package we want to unload.

closePackage

WMEntity closePackage(WMSessionHandle shandle,
                      java.lang.String id,
                      java.lang.String ver)
                      throws java.lang.Exception
Allows administrator to unload the package with the given id and given version from shark. After successful unload, there will no longer be possible to instantiate processes from definitions that were contained within that package.

If version parameter is an empty string or null, all the versions for the given id will be unloaded if possible (otherwise, exception will be thrown).

Parameters:
id - The id of package that is loaded into engine, and has to be closed.
Throws:
java.lang.Exception - If something unexpected happens. PackageInUse exception is thrown if this package is used by any other package that references it as an external package, and is also loaded into engine, PackageHasActiveProcesses is thrown if there are processes written in instance persistence repository, that are instantiated from process definitions contained within package we want to unload.

isPackageReferenced

boolean isPackageReferenced(WMSessionHandle shandle,
                            java.lang.String pkgId)
                            throws java.lang.Exception
Returns information if the current version of package with given id, that is loaded into engine, is referenced from other package (as an external package) that is also loaded into engine.

Parameters:
pkgId - The Id of package we want to check if it is referenced.
Returns:
true if package is referenced from other package, otherwise false.
Throws:
java.lang.Exception - If something unexpected happens.

synchronizeXPDLCache

void synchronizeXPDLCache(WMSessionHandle shandle)
                          throws java.lang.Exception
Synchronizes XPDL caches with the repository state. It is supposed to be used in scenario when there are several VMs using shark, and when one of them loads new XPDL or updates existing.

It checks for all XPDLs in repository, and compares it against the cached ones, and determines which cached instances should be removed from cache permanently, which new instances should be loaded, and which old instances should be reloaded (because the change of their external package instance).

Throws:
java.lang.Exception - If something unexpected happens.

clearXPDLCache

void clearXPDLCache(WMSessionHandle shandle)
                    throws java.lang.Exception
Clears XPDL caches. After clearing caches, first time some XPDL instance is required, the cache is being filled with all instances that exist in DB.

Throws:
java.lang.Exception - If something unexpected happens.

refreshXPDLCache

void refreshXPDLCache(WMSessionHandle shandle)
                      throws java.lang.Exception
Synchronizes XPDL caches with the repository state. It is supposed to be used in scenario when there are several VMs using shark, and when one of them loads new XPDL or updates existing.

It first clears all instances from the cache, and then checks for all XPDLs in repository, and loads them into cache.

Note: for better performance, use #synchronizeXPDLCache method.

Throws:
java.lang.Exception - If something unexpected happens.