com.atlassian.jira.project.version

Interface VersionManager

All Known Implementing Classes:

DefaultVersionManager, MockVersionManager

@PublicApi
public interface VersionManager

Manager responsible for JIRA versions.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ALL_RELEASED_VERSIONS Used to retrieve all released versions
static String	ALL_UNRELEASED_VERSIONS Used to retrieve all unreleased versions
static String	NO_VERSIONS Used to represent empty version fields

Method Summary

Modifier and Type	Method and Description
Version	archiveVersion(Version version, boolean archive) Archive/Un-archive a single version depending on the archive flag.
void	archiveVersions(String[] idsToArchive, String[] idsToUnarchive) Method used to archive and un-archive a number of versions.
Version	createVersion(String name, Date startDate, Date releaseDate, String description, Long projectId, Long scheduleAfterVersion) Deprecated. Since JIRA version 7.0.1, this is deprecated on favour of createVersion(String, java.util.Date, java.util.Date, String, Long, Long, boolean) which lets you specify the release attribute value for the new Version object.
Version	createVersion(String name, Date startDate, Date releaseDate, String description, Long projectId, Long scheduleAfterVersion, boolean released) Creates a new Version.
Version	createVersion(String name, Date releaseDate, String description, Long projectId, Long scheduleAfterVersion) Deprecated. Since JIRA version 7.0.1, this is deprecated on favour of createVersion(String, java.util.Date, java.util.Date, String, Long, Long, boolean) which lets you specify the startDate and release attribute values for the new Version object.
Version	decreaseVersionSequence(Version version) Move a version to have a higher sequence number - ie make it later
void	deleteAllVersions(Long projectId) Deletes all versions in given project.
void	deleteAndRemoveFromIssues(ApplicationUser user, Version versionToRemove) This method deletes a version and additionally (unlinke deleteVersion(com.atlassian.jira.project.version.Version)) removes it from all issues that reference it.
void	deleteVersion(ApplicationUser applicationUser, Version versionToDelete, com.atlassian.fugue.Option<Version> affectsSwapVersion, com.atlassian.fugue.Option<Version> fixSwapVersion) Deprecated. Use deleteVersionAndSwap(ApplicationUser, DeleteVersionWithCustomFieldParameters) that supports swapping version in custom fields. Since v7.0.10
void	deleteVersion(Version version) Removes a specific version from the system.
void	deleteVersionAndSwap(ApplicationUser applicationUser, DeleteVersionWithCustomFieldParameters parameters) Remove specified version.
Version	editVersionDetails(Version version, String name, String description) Updates details of an existing version.
Version	editVersionReleaseDate(Version version, Date duedate) Update the release date of a version.
Version	editVersionStartDate(Version version, Date startDate) Updates the start date of a version
Version	editVersionStartReleaseDate(Version version, Date startDate, Date releaseDate) Updates the start and release date of a version
Collection<Version>	getAffectedVersionsFor(Issue issue) Get all affected versions of the specified issue.
Collection<Version>	getAllVersions()
Collection<Version>	getAllVersionsForProjects(Collection<Project> projects, boolean includeArchived) Returns all versions that belong to the passed projects.
Collection<Version>	getAllVersionsReleased(boolean includeArchived)
Collection<Version>	getAllVersionsUnreleased(boolean includeArchived)
long	getCustomFieldIssuesCount(Version version) This method gives total number of issues where this version is used in custom fields.
Collection<CustomFieldWithVersionUsage>	getCustomFieldsUsing(Version version) This method gives information about usage of given version in custom fields.
Collection<Version>	getFixVersionsFor(Issue issue) Get all fix for versions of the specified issue.
Collection<Long>	getIssueIdsWithAffectsVersion(Version version) Return all the issues in which the affects version matches the specified version.
Collection<Long>	getIssueIdsWithFixVersion(Version version) Return all the issues in which the fix version matches the specified version.
Collection<Issue>	getIssuesWithAffectsVersion(Version version) Return all the issues in which the affected version matches the specified version.
Collection<Issue>	getIssuesWithFixVersion(Version version) Return all the issues in which the fix for version matches the specified version.
Collection<Version>	getOtherUnarchivedVersions(Version version) Return all unarchived versions except this one
Collection<Version>	getOtherVersions(Version version) Return all other versions in the project except this one
Version	getVersion(Long id) Returns a single version.
Version	getVersion(Long projectId, String versionName) Search for a version by projectID and name.
Collection<Version>	getVersions(List<Long> ids) Return a collection of Versions matching the ids passed in.
List<Version>	getVersions(Long projectId) Return a list of Versions for the given project.
List<Version>	getVersions(Long projectId, boolean includeArchived) Return a list of Versions for the given project.
List<Version>	getVersions(Project project) Return a list of Versions for the given project.
Collection<Version>	getVersionsArchived(Project project) Return all archived versions for a particular project.
Collection<Version>	getVersionsByName(String versionName) Return a collection of Versions that have the specified name.
Collection<Version>	getVersionsReleased(Long projectId, boolean includeArchived) Gets a list of released versions for a project.
Collection<Version>	getVersionsReleasedDesc(Long projectId, boolean includeArchived) Gets a list of released versions for a project in reverse order.
Collection<Version>	getVersionsUnarchived(Long projectId) Return all un-archived versions for a particular project
Collection<Version>	getVersionsUnreleased(Long projectId, boolean includeArchived) Gets a list of un-released versions for a particular project.
Version	increaseVersionSequence(Version version) Move a version to have a lower sequence number - ie make it earlier
boolean	isDuplicateName(Version version, String name) Check that the version name we are changing to is not a duplicate.
boolean	isVersionOverDue(Version version) Checks to see if a version is overdue.
void	merge(ApplicationUser user, Version versionToDelete, Version versionToMergeTo) This method will perform a version merge.
void	moveIssuesToNewVersion(List<Issue> issues, Version currentVersion, Version swapToVersion) Swaps the list of issues supplied from one Fix version to another.
Version	moveToEndVersionSequence(Version version) Move a version to the end of the version sequence
Version	moveToStartVersionSequence(Version version) Move a version to the start of the version list
Version	moveVersionAfter(Version version, Long scheduleAfterVersion) Move a version after another version
Version	releaseVersion(Version version, boolean release) Used to release or unrelease a version, depending on the release flag.
Collection<Version>	releaseVersions(Collection<Version> versions, boolean release) Used to release versions depending on the release flag.
void	swapVersionForRelatedIssues(ApplicationUser user, Version version, com.atlassian.fugue.Option<Version> affectsSwapVersion, com.atlassian.fugue.Option<Version> fixSwapVersion) This method will update all issues that currently have version set as either affects or fix version to the new affectsSwapVersion or fixSwapVersion
Version	update(Version version) Persists updates to the specified version object.
List<ChangeItemBean>	updateIssueAffectsVersions(Issue issue, Collection<Version> newValue)
List<ChangeItemBean>	updateIssueFixVersions(Issue issue, Collection<Version> newValue)

Field Detail

NO_VERSIONS

static final String NO_VERSIONS

Used to represent empty version fields

See Also:

Constant Field Values

ALL_UNRELEASED_VERSIONS

static final String ALL_UNRELEASED_VERSIONS

Used to retrieve all unreleased versions

See Also:

Constant Field Values

ALL_RELEASED_VERSIONS

static final String ALL_RELEASED_VERSIONS

Used to retrieve all released versions

See Also:

Constant Field Values

Method Detail

createVersion

Version createVersion(String name,
                      Date releaseDate,
                      String description,
                      Long projectId,
                      Long scheduleAfterVersion)
               throws CreateException

Deprecated. Since JIRA version 7.0.1, this is deprecated on favour of createVersion(String, java.util.Date, java.util.Date, String, Long, Long, boolean) which lets you specify the startDate and release attribute values for the new Version object.

Creates a new Version object.

Parameters:

name - the Name

releaseDate - date of release or null if not released.

description - the Description

projectId - the id of the Project of the version.

scheduleAfterVersion - id of the version after which this should be sequenced or null.

Returns:

the new Version.

Throws:

CreateException - If there was a problem creating the version.

createVersion

@Deprecated
Version createVersion(String name,
                                  Date startDate,
                                  Date releaseDate,
                                  String description,
                                  Long projectId,
                                  Long scheduleAfterVersion)
                           throws CreateException

Deprecated. Since JIRA version 7.0.1, this is deprecated on favour of createVersion(String, java.util.Date, java.util.Date, String, Long, Long, boolean) which lets you specify the release attribute value for the new Version object.

Creates a new Version object.

Parameters:

name - the Name

startDate - start date of the version or null

releaseDate - date of release or null if not released.

description - the Description

projectId - the id of the Project of the version.

scheduleAfterVersion - id of the version after which this should be sequenced or null.

Returns:

the new Version.

Throws:

CreateException - If there was a problem creating the version.

Since:

v6.0

createVersion

Version createVersion(String name,
                      Date startDate,
                      Date releaseDate,
                      String description,
                      Long projectId,
                      Long scheduleAfterVersion,
                      boolean released)
               throws CreateException

Creates a new Version. This method differs from createVersion(String, java.util.Date, java.util.Date, String, Long, Long) in that it lets you specify the value for the attribute release.

Parameters:

name - Name of the version

startDate - Start date of the version

releaseDate - Release date for the version

description - Version description

projectId - The numeric id of the project this version belongs

scheduleAfterVersion - Numeric id of the version to schedule after the given version object

released - Sets the release attribute value for the version object to create

Returns:

The created version object

Throws:

CreateException

Since:

v7.0.1

moveToStartVersionSequence

Version moveToStartVersionSequence(Version version)

Move a version to the start of the version list

Parameters:

version - the Version to move

increaseVersionSequence

Version increaseVersionSequence(Version version)

Move a version to have a lower sequence number - ie make it earlier

Parameters:

version - the Version

decreaseVersionSequence

Version decreaseVersionSequence(Version version)

Move a version to have a higher sequence number - ie make it later

Parameters:

version - the Version

moveToEndVersionSequence

Version moveToEndVersionSequence(Version version)

Move a version to the end of the version sequence

Parameters:

version - the Version

moveVersionAfter

Version moveVersionAfter(Version version,
                         Long scheduleAfterVersion)

Move a version after another version

Parameters:

version - version to reschedule

scheduleAfterVersion - id of the version to schedule after the given version object

deleteVersion

void deleteVersion(Version version)

Removes a specific version from the system.

Parameters:

version - The version to be removed.

See Also:

deleteAndRemoveFromIssues(com.atlassian.jira.user.ApplicationUser, Version)

deleteVersion

void deleteVersion(ApplicationUser applicationUser,
                   Version versionToDelete,
                   com.atlassian.fugue.Option<Version> affectsSwapVersion,
                   com.atlassian.fugue.Option<Version> fixSwapVersion)

Deprecated. Use deleteVersionAndSwap(ApplicationUser, DeleteVersionWithCustomFieldParameters) that supports swapping version in custom fields. Since v7.0.10

Removes a specific version from the system. versionToDelete is the version which is going to be removed. If affectsSwapVersion is defined, then issues with versionToDelete as a value of Affects Version/s system field will use affectsSwapVersion instead. Similarly, fixSwapVersion will replace versionToDelete as a value in Fix Version/s system field.

Parameters:

applicationUser - the user that will be used to update related issues

versionToDelete - the version to be deleted

affectsSwapVersion - the version which replaces the version to be deleted as Affected Version/s.

fixSwapVersion - the version which replaces the version to be deleted as Fix Version/s.

deleteAllVersions

void deleteAllVersions(@Nonnull
                       Long projectId)

Deletes all versions in given project. Note that this method will not fire a VersionDeleteEvent upon deletion of a version.

Parameters:

projectId - the id of project in which versions will be deleted.

editVersionDetails

Version editVersionDetails(Version version,
                           String name,
                           String description)

Updates details of an existing version.

Parameters:

version - The version to update

name - The new version name, cannot be empty.

description - The description of this version.

Throws:

IllegalArgumentException - If the name is not set, or already exists.

isDuplicateName

boolean isDuplicateName(Version version,
                        String name)

Check that the version name we are changing to is not a duplicate.

Parameters:

version - The version to update

name - The new name for the version

Returns:

true if there is already a version with that name for the project

releaseVersion

Version releaseVersion(Version version,
                       boolean release)

Used to release or unrelease a version, depending on the release flag.

Parameters:

version - Version to be released (or unreleased)

release - True to release a version. False to 'unrelease' a version

releaseVersions

Collection<Version> releaseVersions(Collection<Version> versions,
                                    boolean release)

Used to release versions depending on the release flag.

Parameters:

versions - Collection of Versions

release - True to release a version. False to 'unrelease' a version

moveIssuesToNewVersion

void moveIssuesToNewVersion(List<Issue> issues,
                            Version currentVersion,
                            Version swapToVersion)
                     throws IndexException

Swaps the list of issues supplied from one Fix version to another.

Parameters:

issues - the Issues

currentVersion - Current fix version they will be swapped from

swapToVersion - New fix version they will be swapped to.

Throws:

IndexException - if an error occurs will indexing these new issue values.

archiveVersions

void archiveVersions(String[] idsToArchive,
                     String[] idsToUnarchive)

Method used to archive and un-archive a number of versions.

Parameters:

idsToArchive - Archive all these Versions

idsToUnarchive - Unarchive these Versions

archiveVersion

Version archiveVersion(Version version,
                       boolean archive)

Archive/Un-archive a single version depending on the archive flag.

Parameters:

version - the Version to archive or unarchive

archive - new archive value

getVersionsUnarchived

Collection<Version> getVersionsUnarchived(Long projectId)

Return all un-archived versions for a particular project

Parameters:

projectId - id of the project.

Returns:

A collection of Versions

Since:

v3.10

getVersionsArchived

Collection<Version> getVersionsArchived(Project project)

Return all archived versions for a particular project.

Parameters:

project - the Project

Returns:

Archived versions for this project.

update

Version update(Version version)

Persists updates to the specified version object.

Parameters:

version - the version

Returns:

the updated version

Since:

6.0

editVersionReleaseDate

Version editVersionReleaseDate(Version version,
                               Date duedate)

Update the release date of a version.

Parameters:

version - the Version to edit

duedate - new release date

editVersionStartDate

Version editVersionStartDate(Version version,
                             Date startDate)

Updates the start date of a version

Parameters:

version - the version to edit

startDate - new start date

Since:

v6.0

editVersionStartReleaseDate

Version editVersionStartReleaseDate(Version version,
                                    Date startDate,
                                    Date releaseDate)

Updates the start and release date of a version

Parameters:

version - the version to edit

startDate - new start date

releaseDate - new release date

Since:

v6.0

isVersionOverDue

boolean isVersionOverDue(Version version)

Checks to see if a version is overdue. Note: This method checks if the due date set for a version is previous to last midnight. (not now()).

Parameters:

version - the Version

Returns:

True if the version is overdue. (i.e. releaseDate is before last midnight)

getVersions

List<Version> getVersions(Long projectId)

Return a list of Versions for the given project.

Parameters:

projectId - the Project

Returns:

a list of Versions for the given project.

See Also:

getVersions(Project)

getVersions

List<Version> getVersions(Long projectId,
                          boolean includeArchived)

Return a list of Versions for the given project.

Parameters:

projectId - the Project

includeArchived - whether or not to include archived versions

Returns:

a list of Versions for the given project.

See Also:

getVersions(Project)

getVersions

List<Version> getVersions(Project project)

Return a list of Versions for the given project.

Parameters:

project - the Project

Returns:

a list of Versions for the given project.

See Also:

getVersions(Long)

getVersionsByName

Collection<Version> getVersionsByName(String versionName)

Return a collection of Versions that have the specified name.

Parameters:

versionName - the name of the version (case-insensitive)

Returns:

a Collection of Version objects. Never null.

getVersions

Collection<Version> getVersions(List<Long> ids)

Return a collection of Versions matching the ids passed in.

Parameters:

ids - Version IDs

Returns:

a collection of Versions matching the ids passed in.

getVersion

Version getVersion(Long id)

Returns a single version.

Parameters:

id - the Version ID

Returns:

A Version object.

getVersion

Version getVersion(Long projectId,
                   String versionName)

Search for a version by projectID and name.

Parameters:

projectId - the Project

versionName - the Version name

Returns:

A Version object.

getVersionsUnreleased

Collection<Version> getVersionsUnreleased(Long projectId,
                                          boolean includeArchived)

Gets a list of un-released versions for a particular project.

Parameters:

projectId - The id of the project for which to return versions

includeArchived - True if archived versions should be included

Returns:

A Collection of Versions, never null

Since:

v3.10

getVersionsReleased

Collection<Version> getVersionsReleased(Long projectId,
                                        boolean includeArchived)

Gets a list of released versions for a project. This list will include archived versions if the 'includeArchived' flag is set to true.

Parameters:

projectId - project id

includeArchived - flag to indicate whether to include archived versions in the result.

Returns:

A collection of Version objects

getVersionsReleasedDesc

Collection<Version> getVersionsReleasedDesc(Long projectId,
                                            boolean includeArchived)

Gets a list of released versions for a project in reverse order. This list will include archived versions if the 'includeArchived' flag is set to true.

Parameters:

projectId - project id

includeArchived - flag to indicate whether to include archived versions in the result.

Returns:

A collection of Version objects

getOtherVersions

Collection<Version> getOtherVersions(Version version)

Return all other versions in the project except this one

Parameters:

version - the Version

Returns:

all other versions in the project except this one

getOtherUnarchivedVersions

Collection<Version> getOtherUnarchivedVersions(Version version)

Return all unarchived versions except this one

Parameters:

version - the Version

Returns:

all unarchived versions except this one

getIssuesWithFixVersion

Collection<Issue> getIssuesWithFixVersion(Version version)

Return all the issues in which the fix for version matches the specified version.

Parameters:

version - the fixed for version.

Returns:

all the issues in which the fix for version matches the specified version.

Since:

v5.0

getIssuesWithAffectsVersion

Collection<Issue> getIssuesWithAffectsVersion(Version version)

Return all the issues in which the affected version matches the specified version.

Parameters:

version - the affected version.

Returns:

all the issues in which the affected version matches the specified version.

Since:

v5.0

getIssueIdsWithAffectsVersion

Collection<Long> getIssueIdsWithAffectsVersion(@Nonnull
                                               Version version)

Return all the issues in which the affects version matches the specified version.

Parameters:

version - the affects version.

Returns:

all the issues in which the affects version matches the specified version.

Since:

v6.1

getIssueIdsWithFixVersion

Collection<Long> getIssueIdsWithFixVersion(@Nonnull
                                           Version version)

Return all the issues in which the fix version matches the specified version.

Parameters:

version - the fix version.

Returns:

all the issues in which the fix version matches the specified version.

Since:

v6.1

getAffectedVersionsFor

Collection<Version> getAffectedVersionsFor(Issue issue)

Get all affected versions of the specified issue.

Parameters:

issue - the issue

Returns:

all affected versions of the specified issue.

updateIssueAffectsVersions

List<ChangeItemBean> updateIssueAffectsVersions(Issue issue,
                                                Collection<Version> newValue)

updateIssueFixVersions

List<ChangeItemBean> updateIssueFixVersions(Issue issue,
                                            Collection<Version> newValue)

getFixVersionsFor

Collection<Version> getFixVersionsFor(Issue issue)

Get all fix for versions of the specified issue.

Parameters:

issue - the Issue

Returns:

all fix for versions of the specified issue.

getAllVersions

Collection<Version> getAllVersions()

Returns:

all versions in JIRA. Never null.

getAllVersionsForProjects

Collection<Version> getAllVersionsForProjects(Collection<Project> projects,
                                              boolean includeArchived)

Returns all versions that belong to the passed projects.

Parameters:

projects - projects to search in

includeArchived - whether or not to include archived versions

Returns:

all versions that belong to passed projects. Never null.

getAllVersionsReleased

Collection<Version> getAllVersionsReleased(boolean includeArchived)

Parameters:

includeArchived - whether or not to include archived versions

Returns:

all released versions in JIRA. Never null.

getAllVersionsUnreleased

Collection<Version> getAllVersionsUnreleased(boolean includeArchived)

Parameters:

includeArchived - whether or not to include archived versions

Returns:

all released versions in JIRA. Never null.

swapVersionForRelatedIssues

void swapVersionForRelatedIssues(ApplicationUser user,
                                 Version version,
                                 com.atlassian.fugue.Option<Version> affectsSwapVersion,
                                 com.atlassian.fugue.Option<Version> fixSwapVersion)

This method will update all issues that currently have version set as either affects or fix version to the new affectsSwapVersion or fixSwapVersion

Both affectsSwapVersion or fixSwapVersion may be undefined in which case the version will simply be removed from the issue.

Parameters:

user - The user that will be used to update related issues

version - The version to remove from issues

affectsSwapVersion - Affects version to replace version with. May be undefined to simply remove the version.

fixSwapVersion - Fix version to replace version with. May be undefined to simply remove the version.

See Also:

merge(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.version.Version, com.atlassian.jira.project.version.Version), deleteAndRemoveFromIssues(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.version.Version)

merge

void merge(ApplicationUser user,
           @Nonnull
           Version versionToDelete,
           @Nonnull
           Version versionToMergeTo)

This method will perform a version merge. versionToDelete is a version that will be deleted completely. All issues will have this version replaced with versionToMergeTo.

Parameters:

user - The user that will be used to update related issues

versionToDelete - Version that will be deleted

versionToMergeTo - All issues will have deleted version replaced with this one

deleteAndRemoveFromIssues

void deleteAndRemoveFromIssues(ApplicationUser user,
                               @Nonnull
                               Version versionToRemove)

This method deletes a version and additionally (unlinke deleteVersion(com.atlassian.jira.project.version.Version)) removes it from all issues that reference it.

Parameters:

user - User that will perform the update of issues.

versionToRemove - Version to be deleted.

getCustomFieldsUsing

@Nonnull
Collection<CustomFieldWithVersionUsage> getCustomFieldsUsing(@Nonnull
                                                                      Version version)

This method gives information about usage of given version in custom fields.

Parameters:

version - The version that we want to get information about.

Returns:

collection of version usage for each custom fields.

Since:

7.0.10

getCustomFieldIssuesCount

long getCustomFieldIssuesCount(@Nonnull
                               Version version)

This method gives total number of issues where this version is used in custom fields.

Parameters:

version - The version that we want to get information about.

Returns:

collection of version usage for each custom fields.

Since:

7.0.10

deleteVersionAndSwap

void deleteVersionAndSwap(ApplicationUser applicationUser,
                          DeleteVersionWithCustomFieldParameters parameters)

Remove specified version. According to information in DeleteVersionWithCustomFieldParameters version will be completly removed from specific fields are replaced.

Parameters:

applicationUser - The user for this call

parameters - parameters build with builder obtained by VersionService.createVersionDeletaAndReplaceParameters(Version)

Since:

7.0.10

See Also:

merge - if you want to replace all version references to given version.