com.softwareag.centrasite.appl.framework.persistence.versioning
Interface VersionManager

All Known Implementing Classes:
VersionManagerImpl

public interface VersionManager

Version Manager to handle versioning of certain registry beans in CentraSite. The functionality comprises creation of new version objects and purging them. Both interfaces return lists of new/update registry beans. It is up to the user to handle them further (for example saving/deleting) in registry.

The purge returns only registry beans to be delete, hewever there are also repository objects to delete. So after the user commits the delete of purged objects he should call 'removeRepositoryResources()' which cleans up his repository.

 Example 1:   Version a package in DEEP mode (means version also the package members)
 
              RegistryPackage pkg = ...
             
              VersionManager vm = sessionContext.getVersionManager();
              Collection versionObjects = vm.createVersion( pkg, VersionCopyMode.DEEP );
              beanPool.update(versionObjects);
 
 
 Example 2:   Version a service in SHALLOW mode (but ignores its associated *.xsd files)
 
              Service service = ...
              VersionManager vm = sessionContext.getVersionManager();
              Collection versionObjects = vm.createVersion( service, VersionCopyMode.SHALLOW, elinks );
              
              
              
 Example 3:   Purge all older versions of  a service
 
              Service service = getMaxVersionOfService()
              VersionManager vm = sessionContext.getVersionManager();
              Collection deleteObjects = vm.purge( service, 1 );
              beanPool.delete(deleteObjects); 
 


Method Summary
 void addVersionObjectListener(VersionObjectListener versionObjectListener)
          Add a object listener.
 java.util.Collection<RegistryBean> copy(RegistryBean registryBean)
          Copy the specified registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> copy(RegistryBean registryBean, VersionCopyMode copyMode)
          Copy the specified registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> copy(RegistryBean registryBean, VersionCopyMode copyMode, java.util.Collection<RegistryBean> ignoreCopyObjects)
          Copy the specified registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> createVersion(ExternalLink externalLinkObject)
          Create a new version of an External Link.
 java.util.Collection<RegistryBean> createVersion(ExternalLink externalLinkObject, VersionCopyMode copyMode)
          Create a new version of an External Link.
 java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean)
          Create a new version of a registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean, VersionCopyMode copyMode)
          Create a new version of a registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean, VersionCopyMode copyMode, java.util.Collection<RegistryBean> ignoreCopyObjects)
          Create a new version of a registry bean (RegistryEntry or RegistryBean).
 java.util.Collection<RegistryBean> createVersion(Service serviceObject, java.util.Collection<RegistryBean> ignoreCopyObjects)
          Create a new version of a Service object.
 java.util.Collection<RegistryBean> createVersion(Service serviceObject, VersionCopyMode copyMode, java.util.Collection<RegistryBean> ignoreCopyObjects)
          Create a new version of a Service object.
 VersionObjectListener createVersionObjectListener(InternationalString description, java.lang.String userVersion)
          Create a VersionObjectListener
 java.util.Collection<RegistryBean> getAllIgnoredObjects(java.util.Collection<RegistryBean> ignoredObjects)
          Get the entire list of objects to be ignored.
 int getMajorVersion(RegistryBean registryBean)
          Returns the major version number of any registry bean.
 RegistryBean getMaxVersionObject(RegistryBean regObj)
          Get the maximum version object of an arbitrary given object in a versioning row.
 int getMinorVersion(RegistryBean registryBean)
          Returns the minor version number of any registry object.
 java.util.List<RegistryBean> getNewerVersionObjects(RegistryBean registryBean, java.util.Collection<Classification> classifications)
          Get all older versioned objects based on the object given.
 java.util.List<RegistryBean> getOlderVersionObjects(RegistryBean registryBean, java.util.Collection<Classification> classifications)
          Get all older versioned objects based on the object given.
 java.lang.String getUserVersion(RegistryBean registryBean)
          Returns the user version of any registry bean.
 java.util.Collection<RegistryBean> getVersionObjects(RegistryBean registryBean)
          Get all versioned objects based on the object given.
 boolean isMaxVersionObject(RegistryBean regObj)
          Checks if the given object is the maximum (or only) version object
 void overwriteCopyRule(CopyRule copyRule)
          Overwrite a default copy rule.
 java.util.Collection<RegistryBean> purge(java.util.Collection<RegistryBean> registryBeans, int keepCount)
          Purge the list of registry beans with the same keep count.
 java.util.Collection<RegistryBean> purge(RegistryBean registryBean)
          Purge older version registry entries and keep only the actual one.
 java.util.Collection<RegistryBean> purge(RegistryBean registryBean, int keepCount)
          Purge older version registry entries.
 void removeRepositoryResources()
          Remove repository resources collected during purge().
 void removeVersionObjectListener(VersionObjectListener versionObjectListener)
          Remove a object listener.
 void setForceTargetPurge(boolean forceTargetPurge)
          Indicates for the purge methods whether to delete objects although they are target of associations.
 

Method Detail

createVersion

java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean)
                                                 throws CSAppFrameworkException
Create a new version of a registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say this. The object to be versioned must be a top-level versioned and not an intermediate one. The copy mode defaults to NONE.

Parameters:
registryBean - a versionable (or non-versionable) registry bean (version top level)
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean,
                                                 VersionCopyMode copyMode)
                                                 throws CSAppFrameworkException
Create a new version of a registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say this. The object to be versioned must be a top-level versioned and not an intermediate one.

Parameters:
registryBean - a versionable (or non-versionable) registry bean (version top level)
copyMode - the copy mode (SHALLOW, DEEP, ...)
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(RegistryBean registryBean,
                                                 VersionCopyMode copyMode,
                                                 java.util.Collection<RegistryBean> ignoreCopyObjects)
                                                 throws CSAppFrameworkException
Create a new version of a registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say. The object to be versioned must be a top-level versioned and not an intermediate one. The 'ignoreCopyObjects' may contain RegistryBeans (currently only ExternalLink supported) which shouldn't be copied with the DEEP behaviour, but just reused.

Parameters:
registryBean - a versionable (or non-versionable) registry bean (version top level)
copyMode - the copy mode (SHALLOW, DEEP, ...)
ignoreCopyObjects - list of RegistryBean which shouldn't get a new version
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(Service serviceObject,
                                                 java.util.Collection<RegistryBean> ignoreCopyObjects)
                                                 throws CSAppFrameworkException
Create a new version of a Service object. The object to be versioned must be a top-level versioned and not an intermediate one. The copy mode defaults to NONE. The 'ignoreCopyObjects' may contain service-embedded RegistryBeans (currently only ExternalLink supported) which shouldn't be copied with the DEEP behaviour, but just reused.

Parameters:
serviceObject - a Service object (version top level)
ignoreCopyObjects - list of RegistryBean which shouldn't get a new version
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(Service serviceObject,
                                                 VersionCopyMode copyMode,
                                                 java.util.Collection<RegistryBean> ignoreCopyObjects)
                                                 throws CSAppFrameworkException
Create a new version of a Service object. The object to be versioned must be a top-level versioned and not an intermediate one. The 'ignoreCopyObjects' may contain service-embedded RegistryBeans (currently only ExternalLink supported) which shouldn't be copied with the DEEP behaviour, but just reused.

Parameters:
serviceObject - a Service object (version top level)
copyMode - the copy mode (SHALLOW, DEEP, ...)
ignoreCopyObjects - list of RegistryBean which shouldn't get a new version
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(ExternalLink externalLinkObject)
                                                 throws CSAppFrameworkException
Create a new version of an External Link. The copy mode defaults to NONE.

Parameters:
externalLinkObject - the external link
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

createVersion

java.util.Collection<RegistryBean> createVersion(ExternalLink externalLinkObject,
                                                 VersionCopyMode copyMode)
                                                 throws CSAppFrameworkException
Create a new version of an External Link. The DEEP copy mode must only be used for WebDAV resources.

Parameters:
externalLinkObject - the external link
copyMode - the copy mode (NONE, REMOVE, SHALLOW, DEEP)
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

copy

java.util.Collection<RegistryBean> copy(RegistryBean registryBean)
                                        throws CSAppFrameworkException
Copy the specified registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say this. The copy mode defaults to NONE.

Parameters:
registryBean - registry bean to copy
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

copy

java.util.Collection<RegistryBean> copy(RegistryBean registryBean,
                                        VersionCopyMode copyMode)
                                        throws CSAppFrameworkException
Copy the specified registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say this. The copy mode defaults to NONE.

Parameters:
registryBean - registry bean to copy
copyMode - the copy mode (SHALLOW, DEEP, ...)
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

copy

java.util.Collection<RegistryBean> copy(RegistryBean registryBean,
                                        VersionCopyMode copyMode,
                                        java.util.Collection<RegistryBean> ignoreCopyObjects)
                                        throws CSAppFrameworkException
Copy the specified registry bean (RegistryEntry or RegistryBean). If this object is associated with other objects and the copy mode is DEEP, then those objects get duplicated if the association rules say this. The copy mode defaults to NONE. The 'ignoreCopyObjects' may contain RegistryBeans (currently only ExternalLink supported) which shouldn't be copied.

Parameters:
registryBean - registry bean to copy
copyMode - the copy mode (SHALLOW, DEEP, ...)
ignoreCopyObjects - list of RegistryBean which shouldn't get a new version
Returns:
a collection of new version objects
Throws:
CSAppFrameworkException

overwriteCopyRule

void overwriteCopyRule(CopyRule copyRule)
Overwrite a default copy rule. Can be used prior to 'createVersion' to change the DEEP default copy behaviour defined by the individual associations.

Parameters:
copyRule - the copy rule to be used

addVersionObjectListener

void addVersionObjectListener(VersionObjectListener versionObjectListener)
Add a object listener. The listener will be called for object to be versioned / new objects and objects to be purged.

Parameters:
versionObjectListener - the VersionObjectListener

removeVersionObjectListener

void removeVersionObjectListener(VersionObjectListener versionObjectListener)
Remove a object listener.

Parameters:
versionObjectListener - the VersionObjectListener

purge

java.util.Collection<RegistryBean> purge(RegistryBean registryBean)
                                         throws CSAppFrameworkException
Purge older version registry entries and keep only the actual one. The entry specified could be any in the version chain.

Parameters:
registryBean - a registry bean to be purged
Returns:
list of Keys of objects to delete
Throws:
CSAppFrameworkException

purge

java.util.Collection<RegistryBean> purge(RegistryBean registryBean,
                                         int keepCount)
                                         throws CSAppFrameworkException
Purge older version registry entries. The entry specified must could be any in the version chain. The user can specify how much object versions to purge or how much to keep.
 Examples:
     having object versions:  v0 - v1 - v2 - v3 - v4
              
     1.) purge(v4,1)   :   remove v0,v1,v2,v3
     2.) purge(v2,1)   :   remove v0,v1
     3.) purge(v3,2)   :   remove v0,v1
     4.) purge(v3,-1)  :   remove v0
     5.) purge(v4,0)   :   remove all
 
 

Parameters:
registryBean - a registry bean to be purged
keepCount - > 0 : number of version objects to keep; < 0 : number of old object version to delete; 0 : delete all objects
Returns:
list of Keys of objects to delete
Throws:
CSAppFrameworkException

purge

java.util.Collection<RegistryBean> purge(java.util.Collection<RegistryBean> registryBeans,
                                         int keepCount)
                                         throws CSAppFrameworkException
Purge the list of registry beans with the same keep count.

Parameters:
registryBeans - list of registry beans to be deleted
keepCount - > 0 : number of version objects to keep; < 0 : number of old object version to delete; 0 : delete all objects
Returns:
list of Keys of objects to delete
Throws:
CSAppFrameworkException

removeRepositoryResources

void removeRepositoryResources()
Remove repository resources collected during purge(). Should be called after the registry beans to be purged were physically removed from the registry.


getVersionObjects

java.util.Collection<RegistryBean> getVersionObjects(RegistryBean registryBean)
                                                     throws CSAppFrameworkException
Get all versioned objects based on the object given. There is no matter which version the given object has. If the registryEntry has no further version objects, then the result contains only this object.

Parameters:
registryBean - a registry bean (any version)
Returns:
list of all version registry beans
Throws:
CSAppFrameworkException

getOlderVersionObjects

java.util.List<RegistryBean> getOlderVersionObjects(RegistryBean registryBean,
                                                    java.util.Collection<Classification> classifications)
                                                    throws CSAppFrameworkException
Get all older versioned objects based on the object given. The returned list is sorted by the version number in descending order. This means the newest version is the first in the list. If the registry bean has no older versions, then an empty list will be returned.

Parameters:
registryBean - a (versioned) registry bean
classifications - collection of classifications; if not null and not empty then at least one of the classification must match
Returns:
list of all older versions sorted by version number descending
Throws:
CSAppFrameworkException

getNewerVersionObjects

java.util.List<RegistryBean> getNewerVersionObjects(RegistryBean registryBean,
                                                    java.util.Collection<Classification> classifications)
                                                    throws CSAppFrameworkException
Get all older versioned objects based on the object given. The returned list is sorted by the version number in descending order. This means the newest version is the first in the list. If the registry bean has no older versions, then an empty list will be returned.

Parameters:
registryBean - a (versioned) registry bean
classifications - collection of classifications; if not null and not empty then at least one of the classification must match
Returns:
list of all newer versions sorted by version number ascending
Throws:
CSAppFrameworkException

getMaxVersionObject

RegistryBean getMaxVersionObject(RegistryBean regObj)
                                 throws CSAppFrameworkException
Get the maximum version object of an arbitrary given object in a versioning row.

Parameters:
regObj - any registry bean in a versioning row
Returns:
the object with the highest version regObj: if no versioning (or already the highest one)
Throws:
CSAppFrameworkException

isMaxVersionObject

boolean isMaxVersionObject(RegistryBean regObj)
                           throws CSAppFrameworkException
Checks if the given object is the maximum (or only) version object

Parameters:
regObj - a registry bean
Returns:
true: is the maximum (or only) version object false: its an intermediate version object
Throws:
CSAppFrameworkException

getAllIgnoredObjects

java.util.Collection<RegistryBean> getAllIgnoredObjects(java.util.Collection<RegistryBean> ignoredObjects)
                                                        throws CSAppFrameworkException
Get the entire list of objects to be ignored. Main task is to check the entries for associated ones and add them to the resulting list.

Parameters:
ignoredObjects - list of RegistryBean to be ignored
Returns:
list of RegistryBean to be ignored + evtl. more
Throws:
CSAppFrameworkException

setForceTargetPurge

void setForceTargetPurge(boolean forceTargetPurge)
Indicates for the purge methods whether to delete objects although they are target of associations. The default is false.

Parameters:
forceTargetPurge - true: delete objects no matter of target associations; false: reject object delete (implicitely by JAXR) if they are target of associations

createVersionObjectListener

VersionObjectListener createVersionObjectListener(InternationalString description,
                                                  java.lang.String userVersion)
                                                  throws CSAppFrameworkException
Create a VersionObjectListener

Parameters:
description -
userVersion -
Returns:
VersionObjectListener
Throws:
CSAppFrameworkException

getMajorVersion

int getMajorVersion(RegistryBean registryBean)
                    throws CSAppFrameworkException
Returns the major version number of any registry bean. If the object was never versioned then 0 gets returned.

Parameters:
registryBean - a registry bean
Returns:
the major version
Throws:
CSAppFrameworkException - error

getMinorVersion

int getMinorVersion(RegistryBean registryBean)
                    throws CSAppFrameworkException
Returns the minor version number of any registry object. If the object was never versioned then 0 gets returned.

Parameters:
registryBean - a registry bean
Returns:
the minor version
Throws:
CSAppFrameworkException - error

getUserVersion

java.lang.String getUserVersion(RegistryBean registryBean)
                                throws CSAppFrameworkException
Returns the user version of any registry bean. If the object was never versioned then "" gets returned.

Parameters:
registryBean - a registry bean
Returns:
the user version
Throws:
CSAppFrameworkException - error