de.aristaflow.adept2.core.activityrepository

Interface RevisionManager

public interface RevisionManager

The interface for the revision management in the activity repository is separately due to the complexity. It allows to get detailed information on revisions and branches. Additionally, branches may be created, retrieved, updated, released and removed.
Note that revisions and branches are repository-wide, that is, they encompass all entities of the activity repository.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
CheckReport	checkBranch(SessionToken session, long branch, java.util.Locale... locales) Checks the designated branch for inheritance conflicts.
Branch	createBranch(SessionToken session, java.lang.String comment) Creates a new branch with the designated comment.
java.util.Collection<Branch>	getAllBranches(SessionToken session) Gets all branches that are currently in use by this manager.
RemoteIterator<java.util.List<Branch>>	getAllBranchesIterator(SessionToken session) The same as getAllBranches(SessionToken) but with partial retrieval of the branches.
Branch	getBranchData(SessionToken session, long branch) Gets detailed information on the designated branch, that is, the base revision, the creation time of the branch, the last modification time, the creator and a comment.
Revision	getLatestRevision(SessionToken session) Gets detailed information on the latest revision of this activity repository.
Revision	getRevisionData(SessionToken session, long revision) Gets detailed information on the designated revision, that is, the creation time of the revision, the creator and a comment.
void	releaseBranch(SessionToken session, long branch, java.lang.String comment) Releases the designated branch and creates a new production revision which will set all former revisions to outdated.
void	removeBranch(SessionToken session, long branch) Removes the branch by completely dropping all changes.
CheckReport	updateBranch(SessionToken session, long branch, boolean force, java.util.Locale... locales) Updates the designated branch, that is, all changes made to the production revisions since creating or last updating the branch will be incorporated in the branch.

Method Detail

getLatestRevision

Revision getLatestRevision(SessionToken session)

Gets detailed information on the latest revision of this activity repository.

Parameters:

session - The session which is used to check for access rights on this method.

Returns:

Detailed information on the latest revision of this activity repository.

getRevisionData

Revision getRevisionData(SessionToken session,
                         long revision)

Gets detailed information on the designated revision, that is, the creation time of the revision, the creator and a comment.

Parameters:

session - The session which is used to check for access rights on this method.

revision - The revision count for which to retrieve detailed information.

Returns:

Detailed information on the designated revision.

Throws:

UnknownEntityException - If the designated revision does not exist, an UnknownEntityException will be thrown.

getAllBranches

java.util.Collection<Branch> getAllBranches(SessionToken session)

Gets all branches that are currently in use by this manager. Branches are special revisions for development and contain new and/or modified entities of the activity repository.

Parameters:

session - The session which is used to check for access rights on this method.

Returns:

All branches currently used for developing/modifying entities of this activity repository.

getAllBranchesIterator

RemoteIterator<java.util.List<Branch>> getAllBranchesIterator(SessionToken session)

The same as getAllBranches(SessionToken) but with partial retrieval of the branches.

Parameters:

session - The session which is used to check for access rights on this method.

Returns:

All branches currently used for developing/modifying entities of this activity repository as iterator.

getBranchData

Branch getBranchData(SessionToken session,
                     long branch)

Gets detailed information on the designated branch, that is, the base revision, the creation time of the branch, the last modification time, the creator and a comment.

Parameters:

session - The session which is used to check for access rights on this method.

branch - The branch count for which to retrieve detailed information.

Returns:

Detailed information on the designated branch.

Throws:

UnknownEntityException - If the designated branch does not exist, an UnknownEntityException will be thrown.

createBranch

Branch createBranch(SessionToken session,
                    java.lang.String comment)

Creates a new branch with the designated comment. That is, the latest revision is (logically) copied to a branch which allows to modify the entities of the activity model. There may be several branches for the latest or older revisions. However before releasing a branch, they need to be based on the latest revision which can be done by updating them.

Parameters:

session - The session which is used to check for access rights on this method and to identify the creating agent and the corresponding organisational position.

comment - A comment for the newly created branch providing information on the intended changes. This is especially useful when having many concurrent branches.

Returns:

Detailed information on the created branch.

checkBranch

CheckReport checkBranch(SessionToken session,
                        long branch,
                        java.util.Locale... locales)

Checks the designated branch for inheritance conflicts. All entities that are changed in the designated branch will be checked. In case an entity is not changed in the branch, the base revision of it will be used.

Inheritance conflicts may occur for instance when setting an overridden configuration value to fixed or declaring configuration entries which already exist but are incompatible with each other or by attributes that may only be overridden in dedicated ways.
Note that these conflicts are different from versioning conflicts. The latter occur due to concurrent changes in the same entity, inheritance conflicts are due to incompatible changes between two entities in the activity model whereas one entity may override attributes of the other one.

Parameters:

session - The session which is used to check for access rights on this method.

branch - The branch which to check for inheritance conflicts.

locales - The locale(s) for the messages in the check report. If this is null, Locale.ROOT will be used.

Returns:

A check report containing any conflicts (or no conflicts) currently present in the designated branch.

updateBranch

CheckReport updateBranch(SessionToken session,
                         long branch,
                         boolean force,
                         java.util.Locale... locales)

Updates the designated branch, that is, all changes made to the production revisions since creating or last updating the branch will be incorporated in the branch. If there are any conflicts, the returned check report will provide them and the update will be aborted. These (versioning) conflicts occur when changing the attributes of the very same entity in a production revision as well as in the designated development branch.
Updating a branch is necessary before releasing it since otherwise changes applied to a production revision may be lost. Revision conflicts when updating have to be resolved manually be the user. However, to simplify this, each entity can be checked separately for revision conflicts. Additionally, an update can be forced in which case only the base revision of the branch will be adapted but the attribute values remain the same. This will loose all changes made to the production revision. Since the name cannot be changed, the name attribute will not be forced from the branch but from the production revision, that is, this attribute is forced the other way.

Parameters:

session - The session which is used to check for access rights on this method

branch - The branch which to update (and check for versioning conflicts).

force - Whether conflicting attributes should be taken from the development branch and the ones from the latest production revision.

locales - The locale(s) for the messages in the check report. If this is null, Locale.ROOT will be used.

Returns:

A check report containing every versioning conflict in the designated branch. If this contains no conflicts, the branch will be updated, that is its base revision will be changed to the latest production revision.

Throws:

UnknownEntityException - If the designated branch does not exist, an UnknownEntityException will be thrown.

releaseBranch

void releaseBranch(SessionToken session,
                   long branch,
                   java.lang.String comment)
            throws RevisionConflictException,
                   InheritanceConflictException

Releases the designated branch and creates a new production revision which will set all former revisions to outdated. This will only be performed in case the branch does not contain any inheritance conflicts and it is based on the latest revision. Therefore one should check the branch before releasing. Releasing includes checking for revision and inheritance conflicts, adapting the revision and the states of all involved entities as well as removing the branch. Therefore after releasing a branch will be empty.
The comment for the release is the same as the comment of the corresponding branch.

Parameters:

session - The session which is used to check for access rights on this method and to identify the releasing agent and the corresponding organisational position.

branch - The branch which to release.

comment - The comment for the new revision to be created. Use null to adopt the branch's comment as release comment.

Throws:

RevisionConflictException - If there are revision conflicts, that is the branch is not based on the latest revision of the repository, a RevisionConflictException will be thrown. You will have to update the branch beforehand.

InheritanceConflictException - If there are conflicts due to inheritance, for instance, a child entity overrides a fixed configuration entry of a parent entity, an InheritanceConflictException will be thrown. Use checkBranch(SessionToken, long, Locale...) for detailed information on the inheritance conflicts.

removeBranch

void removeBranch(SessionToken session,
                  long branch)

Removes the branch by completely dropping all changes. Afterwards the branch will not be available any more; no changes will be reflected in the production revisions.

Parameters:

session - The session which is used to check for access rights on this method.

branch - The branch to remove completely including all changed entities in it.

Throws:

UnknownEntityException - If the designated branch is currently unused, an UnknownEntityException will be thrown.