@PublicApi public interface

VersionManager

com.atlassian.jira.project.version.VersionManager
Known Indirect Subclasses

@PublicApi

This interface is designed for plugins to consume (call its methods).

Clients of @PublicApi can expect that programs compiled against a given version will remain binary compatible with later versions of the @PublicApi as per each product's API policy as long as the client does not implement/extend @PublicApi interfaces or classes (refer to each product's API policy for the exact guarantee---usually binary compatibility is guaranteed at least across minor versions).

Note: since @PublicApi interfaces and classes are not designed to be implemented or extended by clients, we may perform certain types of binary-incompatible changes to these classes and interfaces, but these will not affect well-behaved clients that do not extend/implement these types (in general, only classes and interfaces annotated with @PublicSpi are safe to extend/implement).

Class Overview

Manager responsible for JIRA versions.

Summary

Constants
String ALL_RELEASED_VERSIONS Used to retrieve all released versions
String ALL_UNRELEASED_VERSIONS Used to retrieve all unreleased versions
String NO_VERSIONS Used to represent empty version fields
Public Methods
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 releaseDate, String description, Long projectId, Long scheduleAfterVersion)
This method is 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 createVersion(String name, Date startDate, Date releaseDate, String description, Long projectId, Long scheduleAfterVersion, boolean released)
Creates a new Version.
@Deprecated Version createVersion(String name, Date startDate, Date releaseDate, String description, Long projectId, Long scheduleAfterVersion)
This method is 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 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(Version)) removes it from all issues that reference it.
void deleteVersion(ApplicationUser applicationUser, Version versionToDelete, Option<Version> affectsSwapVersion, Option<Version> fixSwapVersion)
Removes a specific version from the system.
void deleteVersion(Version version)
Removes a specific version from the system.
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)
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 projectId, String versionName)
Search for a version by projectID and name.
Version getVersion(Long id)
Returns a single version.
List<Version> getVersions(Project project)
Return a list of Versions for the given project.
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.
Collection<Version> getVersions(List<Long> ids)
Return a collection of Versions matching the ids passed in.
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, Option<Version> affectsSwapVersion, 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.

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)

Constants

public static final String ALL_RELEASED_VERSIONS

Used to retrieve all released versions

Constant Value: "-3"

public static final String ALL_UNRELEASED_VERSIONS

Used to retrieve all unreleased versions

Constant Value: "-2"

public static final String NO_VERSIONS

Used to represent empty version fields

Constant Value: "-1"

Public Methods

public 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

public 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

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

This method is 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.

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

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

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

This method is 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.

public Version decreaseVersionSequence (Version version)

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

Parameters
version the Version

public void deleteAllVersions (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.

public void deleteAndRemoveFromIssues (ApplicationUser user, Version versionToRemove)

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

Parameters
user User that will perform the update of issues.
versionToRemove Version to be deleted.

public void deleteVersion (ApplicationUser applicationUser, Version versionToDelete, Option<Version> affectsSwapVersion, Option<Version> fixSwapVersion)

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.

public void deleteVersion (Version version)

Removes a specific version from the system.

Parameters
version The version to be removed.
See Also

public 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.

public Version editVersionReleaseDate (Version version, Date duedate)

Update the release date of a version.

Parameters
version the Version to edit
duedate new release date

public Version editVersionStartDate (Version version, Date startDate)

Updates the start date of a version

Parameters
version the version to edit
startDate new start date

public 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

public 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.

public Collection<Version> getAllVersions ()

Returns
  • all versions in JIRA. Never null.

public 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.

public Collection<Version> getAllVersionsReleased (boolean includeArchived)

Parameters
includeArchived whether or not to include archived versions
Returns
  • all released versions in JIRA. Never null.

public Collection<Version> getAllVersionsUnreleased (boolean includeArchived)

Parameters
includeArchived whether or not to include archived versions
Returns
  • all released versions in JIRA. Never null.

public 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.

public Collection<Long> getIssueIdsWithAffectsVersion (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.

public Collection<Long> getIssueIdsWithFixVersion (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.

public 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.

public 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.

public Collection<Version> getOtherUnarchivedVersions (Version version)

Return all unarchived versions except this one

Parameters
version the Version
Returns
  • all unarchived versions except this one

public 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

public Version getVersion (Long projectId, String versionName)

Search for a version by projectID and name.

Parameters
projectId the Project
versionName the Version name
Returns

public Version getVersion (Long id)

Returns a single version.

Parameters
id the Version ID
Returns

public 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

public 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

public 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

public 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.

public Collection<Version> getVersionsArchived (Project project)

Return all archived versions for a particular project.

Parameters
project the Project
Returns
  • Archived versions for this project.

public 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.

public 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

public 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

public Collection<Version> getVersionsUnarchived (Long projectId)

Return all un-archived versions for a particular project

Parameters
projectId id of the project.
Returns

public 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

public Version increaseVersionSequence (Version version)

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

Parameters
version the Version

public 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

public 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)

public void merge (ApplicationUser user, Version versionToDelete, 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

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

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.

public Version moveToEndVersionSequence (Version version)

Move a version to the end of the version sequence

Parameters
version the Version

public Version moveToStartVersionSequence (Version version)

Move a version to the start of the version list

Parameters
version the Version to move

public 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

public 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

public 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

public void swapVersionForRelatedIssues (ApplicationUser user, Version version, Option<Version> affectsSwapVersion, 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

public Version update (Version version)

Persists updates to the specified version object.

Parameters
version the version
Returns
  • the updated version

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

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