com.atlassian.jira.bc.project.version

Class DefaultVersionService

java.lang.Object

com.atlassian.jira.bc.project.version.DefaultVersionService

All Implemented Interfaces:

VersionService

public class DefaultVersionService
extends Object
implements VersionService

Since:

v3.13

Nested Class Summary

Nested classes/interfaces inherited from interface com.atlassian.jira.bc.project.version.VersionService

VersionService.AbstractVersionResult, VersionService.ArchiveVersionValidationResult, VersionService.CreateVersionValidationResult, VersionService.MoveVersionValidationResult, VersionService.ReasonsServiceResult<R,T>, VersionService.ReleaseVersionValidationResult, VersionService.ValidationResult, VersionService.VersionAction, VersionService.VersionBuilderValidationResult, VersionService.VersionExtractableField, VersionService.VersionResult, VersionService.VersionsResult

Field Summary

Fields inherited from interface com.atlassian.jira.bc.project.version.VersionService

REMOVE

Constructor Summary

Constructors

Constructor and Description
DefaultVersionService(VersionManager versionManager, PermissionManager permissionManager, IssueManager issueManager, SearchService searchService, I18nHelper.BeanFactory i18n, DateFieldFormat dateFieldFormat, ProjectManager projectManager)

Method Summary

Modifier and Type	Method and Description
Version	archiveVersion(VersionService.ArchiveVersionValidationResult result) Takes a validation result and performs the archive operation.
ServiceOutcome<Version>	create(ApplicationUser user, VersionService.VersionBuilderValidationResult validationResult) Creates a new Version, based on the validation result from calling #validateCreate(User, VersionBuilder).
Version	createVersion(ApplicationUser user, VersionService.CreateVersionValidationResult request) Using the validation result from #validateCreateVersion(User, com.atlassian.jira.project.Project, String, String, String, Long) a new version will be created.
DeleteVersionWithReplacementsParameterBuilder	createVersionDeletaAndReplaceParameters(Version versionToDelete) Create builder that for paramaters to remove version with swap (including custom fields)
void	decreaseVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult) Move a version to have a higher sequence number - ie make it later.
void	delete(JiraServiceContext context, VersionService.ValidationResult result) Deletes a version from a project.
ServiceResult	deleteVersionAndSwap(JiraServiceContext serviceContext, DeleteVersionWithCustomFieldParameters parameters) Remove specified version.
long	getAffectsIssuesCount(Version version) Return the count of Issues that have the "Affects Version" field set to version.
long	getCustomFieldIssuesCount(Version version) This method returns the total number of issues where this version is used in custom fields
Collection<CustomFieldWithVersionUsage>	getCustomFieldsUsing(Version version) This method returns usage information in custom fields for a given version.
long	getFixIssuesCount(Version version) Return the count of Issues Fixed in this version.
long	getUnresolvedIssuesCount(ApplicationUser user, Version version) Return the count of Issues that are unresolved in this version.
VersionService.VersionResult	getVersionById(ApplicationUser user, Long versionId) Used to retrieve a Version object by version id.
VersionService.VersionResult	getVersionById(ApplicationUser user, Project project, Long versionId) Used to retrieve a Version object by version id within project specified by Project object.
VersionService.VersionResult	getVersionByProjectAndName(ApplicationUser user, Project project, String versionName) Used to retrieve a Version object by version name within project specified by Project object.
VersionService.VersionsResult	getVersionsByProject(ApplicationUser user, Project project) Used to retrieve a Version collection within project specified by Project object.
ServiceOutcome<Page<Version>>	getVersionsByProject(ApplicationUser user, Project project, PageRequest pageRequest) This method returns all versions for a given project.
ServiceOutcome<Page<Version>>	getVersionsByProject(ApplicationUser user, Project project, PageRequest pageRequest, io.atlassian.fugue.Option<OrderByRequest<VersionService.VersionExtractableField>> orderBy)
ServiceOutcome<Page<Version>>	getVersionsByProject(ApplicationUser user, Project project, PageRequest pageRequest, OrderByRequest<VersionService.VersionExtractableField> orderBy) This method returns all versions for a given project.
void	increaseVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult) Move a version to have a lower sequence number - ie make it earlier.
boolean	isOverdue(Version version) Is the passed version overdue? This method does no permission checks on the passed version.
void	merge(JiraServiceContext context, VersionService.ValidationResult result) Merges a version into another, then removes the original version.
void	moveToEndVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult) Move a version to the end of the version sequence.
void	moveToStartVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult) Move a version to the start of the version list.
void	moveUnreleasedToNewVersion(ApplicationUser directoryUser, Version currentVersion, Version newVersion) Using the validation result from #validateReleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be released.
void	moveVersionAfter(VersionService.MoveVersionValidationResult moveVersionValidationResult) Move a version after another version.
VersionBuilder	newVersionBuilder() Creates a builder to be used when creating a new Version.
VersionBuilder	newVersionBuilder(Version version) Creates a builder to be used when updating an existing Version.
protected Date	parseDate(ApplicationUser user, com.atlassian.jira.bc.project.version.DefaultVersionService.DateField field, String date) Parses a string release date into a Date object, throwing an exception if there is a problem parsing the string.
Version	releaseVersion(VersionService.ReleaseVersionValidationResult result) Using the validation result from #validateReleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be released.
ServiceOutcome<Version>	setReleaseDate(ApplicationUser user, Version version, Date releaseDate) Modify the release date of a version without performing a release/unrelease.
ServiceOutcome<Version>	setReleaseDate(ApplicationUser user, Version version, String releaseDate) Modify the release date of a version without performing a release/unrelease.
ServiceOutcome<Version>	setVersionDetails(ApplicationUser user, Version version, String name, String description) Set the name and description of a version, if you have edit permission.
Version	unarchiveVersion(VersionService.ArchiveVersionValidationResult result) Takes a validation result and performs the unarchive operation.
Version	unreleaseVersion(VersionService.ReleaseVersionValidationResult result) Using the validation result from #validateUnreleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be unreleased.
ServiceOutcome<Version>	update(ApplicationUser user, VersionService.VersionBuilderValidationResult validationResult) Updates the existing Version, based on the validation result from calling #validateUpdate(User, VersionBuilder).
VersionService.ArchiveVersionValidationResult	validateArchiveVersion(ApplicationUser user, Version version) This method should be called before archiving a version.
VersionService.VersionBuilderValidationResult	validateCreate(ApplicationUser user, VersionBuilder versionBuilder) Validates the creation of a new Version object, specified with a VersionBuilder.
VersionService.CreateVersionValidationResult	validateCreateVersion(ApplicationUser user, Project project, String versionName, Date releaseDate, String description, Long scheduleAfterVersion) This method needs to be called before creating a version to ensure all parameters are correct.
VersionService.CreateVersionValidationResult	validateCreateVersion(ApplicationUser user, Project project, String versionName, String releaseDateStr, String description, Long scheduleAfterVersion) This method needs to be called before creating a version to ensure all parameters are correct.
VersionService.MoveVersionValidationResult	validateDecreaseVersionSequence(ApplicationUser user, long versionId) Validate Move a version to have a higher sequence number - ie make it later.
VersionService.ValidationResult	validateDelete(JiraServiceContext context, Long versionId, VersionService.VersionAction affectsAction, VersionService.VersionAction fixAction) Validates an attempt to delete a version from a project.
VersionService.MoveVersionValidationResult	validateIncreaseVersionSequence(ApplicationUser user, long versionId) Validate Move a version to have a lower sequence number - ie make it earlier.
VersionService.ValidationResult	validateMerge(JiraServiceContext context, Long versionId, Long swapVersionId) Implementation is the same as deleting, with the actions set to SWAP and the swapVersionId being passed as both Affects Version swap and Fix Version swap
VersionService.MoveVersionValidationResult	validateMoveToEndVersionSequence(ApplicationUser user, long versionId) Validate Move a version to the end of the version sequence.
VersionService.MoveVersionValidationResult	validateMoveToStartVersionSequence(ApplicationUser user, long versionId) Validate Move a version to the start of the version list.
VersionService.MoveVersionValidationResult	validateMoveVersionAfter(ApplicationUser user, long versionId, Long scheduleAfterVersionId) Validate Move a version after another version.
ServiceOutcome<Version>	validateReleaseDate(ApplicationUser user, Version version, String releaseDate) Validate the release date of a version without performing a release/unrelease.
VersionService.ReleaseVersionValidationResult	validateReleaseVersion(ApplicationUser user, Version version, Date releaseDate) This method needs to be called before releasing a version to ensure all parameters are correct.
VersionService.ReleaseVersionValidationResult	validateReleaseVersion(ApplicationUser user, Version version, String releaseDate) This method needs to be called before releasing a version to ensure all parameters are correct.
protected ServiceOutcome<Void>	validateStartReleaseDates(ApplicationUser user, com.atlassian.jira.bc.project.version.DefaultVersionService.DateField field, Date startDate, Date releaseDate)
VersionService.ArchiveVersionValidationResult	validateUnarchiveVersion(ApplicationUser user, Version version) This method should be called before unarchiving a version.
VersionService.ReleaseVersionValidationResult	validateUnreleaseVersion(ApplicationUser user, Version version, Date releaseDate) This method needs to be called before unreleasing a version to ensure all parameters are correct.
VersionService.ReleaseVersionValidationResult	validateUnreleaseVersion(ApplicationUser user, Version version, String releaseDate) This method needs to be called before unreleasing a version to ensure all parameters are correct.
VersionService.VersionBuilderValidationResult	validateUpdate(ApplicationUser user, VersionBuilder versionBuilder) Validates the update of an existing Version object, specified with a VersionBuilder.
ErrorCollection	validateVersionDetails(ApplicationUser user, Version version, String name, String description) Validate the name and description of a version, if you have edit permission.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultVersionService

public DefaultVersionService(VersionManager versionManager,
                             PermissionManager permissionManager,
                             IssueManager issueManager,
                             SearchService searchService,
                             I18nHelper.BeanFactory i18n,
                             DateFieldFormat dateFieldFormat,
                             ProjectManager projectManager)

Method Detail

getVersionById

public VersionService.VersionResult getVersionById(@Nullable
                                                   ApplicationUser user,
                                                   Project project,
                                                   Long versionId)

Description copied from interface: VersionService

Used to retrieve a Version object by version id within project specified by Project object. This method returns a VersionService.VersionResult. The version will be null if no version for the id specified can be found, or if the user making the request does not have the ADMIN, PROJECT_ADMIN or BROWSE project permission for the project. In both of these cases, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionById in interface VersionService

Parameters:

user - The user trying to get a version

project - The project object containing requested version

versionId - The id of requested version

Returns:

VersionResult object

getVersionById

public VersionService.VersionResult getVersionById(ApplicationUser user,
                                                   Long versionId)

Description copied from interface: VersionService

Used to retrieve a Version object by version id. This method returns a VersionService.VersionResult. The version will be null if no version for the id specified can be found, or if the user making the request does not have the ADMIN, PROJECT_ADMIN or BROWSE project permission for the project. In both of these cases, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionById in interface VersionService

Parameters:

user - The user trying to get a version

versionId - The id of requested version

Returns:

VersionResult object

getVersionByProjectAndName

@Nonnull
public VersionService.VersionResult getVersionByProjectAndName(@Nullable
                                                                        ApplicationUser user,
                                                                        @Nonnull
                                                                        Project project,
                                                                        @Nonnull
                                                                        String versionName)

Description copied from interface: VersionService

Used to retrieve a Version object by version name within project specified by Project object. This method returns a VersionService.VersionResult. The version will be null if no version for the versionName specified can be found, or if the user making the request does not have the ADMIN, PROJECT_ADMIN or BROWSE project permission for the project. In both of these cases, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionByProjectAndName in interface VersionService

Parameters:

user - The user trying to get a version

project - The project object containing requested version

versionName - The name of requested version

Returns:

VersionResult containing errors and the Version if it could be found

getVersionsByProject

@Nonnull
public VersionService.VersionsResult getVersionsByProject(@Nullable
                                                                   ApplicationUser user,
                                                                   @Nonnull
                                                                   Project project)

Description copied from interface: VersionService

Used to retrieve a Version collection within project specified by Project object. This method returns a VersionService.VersionsResult. The versions collection will be empty if the user making the request does not have the ADMIN, PROJECT_ADMIN or BROWSE project permission for the project. In this case, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionsByProject in interface VersionService

Parameters:

user - The user trying to get a version

project - The project object containing requested version

Returns:

VerionsResult object

getVersionsByProject

@Nonnull
public ServiceOutcome<Page<Version>> getVersionsByProject(@Nullable
                                                                   ApplicationUser user,
                                                                   @Nonnull
                                                                   Project project,
                                                                   @Nonnull
                                                                   PageRequest pageRequest)

Description copied from interface: VersionService

This method returns all versions for a given project. It's similar to the VersionService.getVersionsByProject(ApplicationUser, Project) but the results it returns are paged.

The user making the request must have the ADMIN, PROJECT_ADMIN or BROWSE project permissions for the project. Otherwise, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionsByProject in interface VersionService

Parameters:

user - The user trying to get a version

project - The project object containing requested version

pageRequest - details of a page to return (offset, max number of results)

Returns:

A single page of versions or an appropriate error message if the user does not have permissions to read versions for the project

See Also:

VersionService.getVersionsByProject(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project, com.atlassian.jira.util.PageRequest, com.atlassian.jira.util.OrderByRequest)

getVersionsByProject

@Nonnull
public ServiceOutcome<Page<Version>> getVersionsByProject(@Nullable
                                                                   ApplicationUser user,
                                                                   @Nonnull
                                                                   Project project,
                                                                   @Nonnull
                                                                   PageRequest pageRequest,
                                                                   @Nullable
                                                                   OrderByRequest<VersionService.VersionExtractableField> orderBy)

Description copied from interface: VersionService

This method returns all versions for a given project. It's similar to the VersionService#getVersionsByProject(ApplicationUser, Project) but the results it returns are paged.

It also provides the possibility to sort the results by the fields specified in the VersionService.VersionExtractableField class.

The user making the request must have the ADMIN, PROJECT_ADMIN or BROWSE project permissions for the project. Otherwise, the errorCollection in the result object will contain an appropriate error message.

Specified by:

getVersionsByProject in interface VersionService

Parameters:

user - The user trying to get a version

project - The project object containing requested version

pageRequest - details of a page to return (offset, max number of results)

orderBy - details on how to order the results

Returns:

A single page of versions or an appropriate error message if the user does not have permissions to read versions for the project

See Also:

VersionService.getVersionsByProject(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.project.Project, com.atlassian.jira.util.PageRequest)

setVersionDetails

public ServiceOutcome<Version> setVersionDetails(ApplicationUser user,
                                                 Version version,
                                                 String name,
                                                 String description)

Description copied from interface: VersionService

Set the name and description of a version, if you have edit permission.

Specified by:

setVersionDetails in interface VersionService

Parameters:

user - the user who is performing the edit operation

version - the version that they want to edit

name - the new name for the version (must not be null or already in use)

description - the new description for the version

Returns:

a ServiceOutcome that contains the success or failure of the update

validateVersionDetails

public ErrorCollection validateVersionDetails(ApplicationUser user,
                                              Version version,
                                              String name,
                                              String description)

Description copied from interface: VersionService

Validate the name and description of a version, if you have edit permission.

Specified by:

validateVersionDetails in interface VersionService

Parameters:

user - the user who is performing the edit operation

version - the version that they want to edit

name - the new name for the version (must not be null or already in use)

description - the new description for the version

Returns:

an ErrorCollection that contains the success or failure of the update

setReleaseDate

public ServiceOutcome<Version> setReleaseDate(ApplicationUser user,
                                              Version version,
                                              Date releaseDate)

Description copied from interface: VersionService

Modify the release date of a version without performing a release/unrelease.

Specified by:

setReleaseDate in interface VersionService

Parameters:

user - the user who is changing the release date

version - the version they want to modify

releaseDate - the new release date to use

Returns:

a ServiceOutcome describing the success/failure of the edit, along with the new Version if successful

validateReleaseDate

public ServiceOutcome<Version> validateReleaseDate(ApplicationUser user,
                                                   Version version,
                                                   String releaseDate)

Description copied from interface: VersionService

Validate the release date of a version without performing a release/unrelease.

Specified by:

validateReleaseDate in interface VersionService

Parameters:

user - the user who is changing the release date

version - the version they want to modify

releaseDate - the new release date to use

Returns:

a ServiceOutcome describing the success/failure of the edit, along with the new Version if successful

setReleaseDate

public ServiceOutcome<Version> setReleaseDate(ApplicationUser user,
                                              Version version,
                                              String releaseDate)

Description copied from interface: VersionService

Modify the release date of a version without performing a release/unrelease.

Specified by:

setReleaseDate in interface VersionService

Parameters:

user - the user who is changing the release date

version - the version they want to modify

releaseDate - the new release date to use

Returns:

a ServiceOutcome describing the success/failure of the edit, along with the new Version if successful

validateDelete

public VersionService.ValidationResult validateDelete(JiraServiceContext context,
                                                      Long versionId,
                                                      VersionService.VersionAction affectsAction,
                                                      VersionService.VersionAction fixAction)

Description copied from interface: VersionService

Validates an attempt to delete a version from a project. When deleting a version, we need to decide what to do with issues that reference the version in their Affects of Fix Version fields. The action taken is specified as a flag for each field.

Specified by:

validateDelete in interface VersionService

Parameters:

context - The context for this service call.

versionId - The id of the version to be deleted.

affectsAction - Used to decide whether to move all the issues to a different 'affects' version or just remove them. See VersionKeys.REMOVE_ACTION, VersionKeys.SWAP_ACTION

fixAction - Used to decide wether to move all the issues to a different 'fix' version or just remove them. See VersionKeys.REMOVE_ACTION, VersionKeys.SWAP_ACTION

Returns:

a VersionService.ValidationResult object which contains the version to delete, and the versions to swap to for Affects and Fix versions, or null if the action to be taken is VersionKeys.REMOVE_ACTION

delete

public void delete(JiraServiceContext context,
                   VersionService.ValidationResult result)

Description copied from interface: VersionService

Deletes a version from a project. When deleting a version, we need to decide what to do with issues that reference the version in their Affects of Fix Version fields. The action taken is specified as a flag for each field.

Specified by:

delete in interface VersionService

Parameters:

context - The context for this service call.

result - The result of validation, which contains the version to be deleted, and the swap versions for Affects and Fix fields

createVersionDeletaAndReplaceParameters

public DeleteVersionWithReplacementsParameterBuilder createVersionDeletaAndReplaceParameters(@Nonnull
                                                                                             Version versionToDelete)

Description copied from interface: VersionService

Create builder that for paramaters to remove version with swap (including custom fields)

Specified by:

createVersionDeletaAndReplaceParameters in interface VersionService

Parameters:

versionToDelete - version that will be deleted - mandatory

See Also:

VersionService.deleteVersionAndSwap(JiraServiceContext, DeleteVersionWithCustomFieldParameters)

deleteVersionAndSwap

public ServiceResult deleteVersionAndSwap(@Nonnull
                                          JiraServiceContext serviceContext,
                                          @Nonnull
                                          DeleteVersionWithCustomFieldParameters parameters)

Description copied from interface: VersionService

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

Specified by:

deleteVersionAndSwap in interface VersionService

Parameters:

serviceContext - The context for this service call.

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

Returns:

result than holds eventual errors in removal

See Also:

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

validateMerge

public VersionService.ValidationResult validateMerge(JiraServiceContext context,
                                                     Long versionId,
                                                     Long swapVersionId)

Implementation is the same as deleting, with the actions set to SWAP and the swapVersionId being passed as both Affects Version swap and Fix Version swap

Specified by:

validateMerge in interface VersionService

Parameters:

context - The context for this service call.

versionId - The original version to be merged and removed.

swapVersionId - The target version of the merge operation. Must be from the same project.

Returns:

a VersionService.ValidationResult object which contains the version to delete, and the versions to swap to for Affects and Fix versions, or null if the action to be taken is VersionKeys.REMOVE_ACTION

merge

public void merge(JiraServiceContext context,
                  VersionService.ValidationResult result)

Description copied from interface: VersionService

Merges a version into another, then removes the original version.

Specified by:

merge in interface VersionService

Parameters:

context - The context for this service call.

result - The result of validation, which contains the version to be deleted, and the swap versions for Affects and Fix fields

validateCreateVersion

public VersionService.CreateVersionValidationResult validateCreateVersion(ApplicationUser user,
                                                                          Project project,
                                                                          String versionName,
                                                                          String releaseDateStr,
                                                                          String description,
                                                                          Long scheduleAfterVersion)

Description copied from interface: VersionService

This method needs to be called before creating a version to ensure all parameters are correct. There are a number of required parameters, such as a project object and versionName. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version with the name provided already exists and throw an appropriate error.

Optional validation will be done for the release date, if provided. An error will be returned, if date format is valid.

The method will return a VersionService.CreateVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateCreateVersion in interface VersionService

Parameters:

user - The user trying to create a version

project - The project object containing requested version

versionName - The name of created version

releaseDateStr - The release date for a version (optional)

description - The description for a version (optional)

scheduleAfterVersion - The version after which created version should be scheduled (optional)

Returns:

CreateVersionValidationResult object

validateCreateVersion

public VersionService.CreateVersionValidationResult validateCreateVersion(ApplicationUser user,
                                                                          Project project,
                                                                          String versionName,
                                                                          Date releaseDate,
                                                                          String description,
                                                                          Long scheduleAfterVersion)

Description copied from interface: VersionService

This method needs to be called before creating a version to ensure all parameters are correct. There are a number of required parameters, such as a project object and versionName. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version with the name provided already exists and throw an appropriate error.

Optional validation will be done for the release date, if provided. An error will be returned, if date format is valid.

The method will return a VersionService.CreateVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateCreateVersion in interface VersionService

Parameters:

user - The user trying to create a version

project - The project object containing requested version

versionName - The name of created version

releaseDate - The release date for a version (optional)

description - The description for a version (optional)

scheduleAfterVersion - The version after which created version should be scheduled (optional)

Returns:

CreateVersionValidationResult object

createVersion

public Version createVersion(ApplicationUser user,
                             VersionService.CreateVersionValidationResult request)

Description copied from interface: VersionService

Using the validation result from #validateCreateVersion(User, com.atlassian.jira.project.Project, String, String, String, Long) a new version will be created. This method will throw an RuntimeException if the version could not be created.

Specified by:

createVersion in interface VersionService

Parameters:

user - The user trying to get a version

request - The VersionService.CreateVersionValidationResult object containing all required data

Returns:

created Version object

validateReleaseVersion

@Nonnull
public VersionService.ReleaseVersionValidationResult validateReleaseVersion(@Nullable
                                                                                     ApplicationUser user,
                                                                                     @Nonnull
                                                                                     Version version,
                                                                                     @Nullable
                                                                                     Date releaseDate)

Description copied from interface: VersionService

This method needs to be called before releasing a version to ensure all parameters are correct. There is required parameter, version object. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version provided has a valid name and if is not released already.

The method will return a VersionService.ReleaseVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateReleaseVersion in interface VersionService

Parameters:

user - The user trying to release a version

version - The version to release

releaseDate - The version release date (optional)

Returns:

ReleaseVersionValidationResult object

validateReleaseVersion

@Nonnull
public VersionService.ReleaseVersionValidationResult validateReleaseVersion(@Nullable
                                                                                     ApplicationUser user,
                                                                                     @Nonnull
                                                                                     Version version,
                                                                                     @Nullable
                                                                                     String releaseDate)

Description copied from interface: VersionService

This method needs to be called before releasing a version to ensure all parameters are correct. There is required parameter, version object. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version provided has a valid name and if is not released already.

The method will return a VersionService.ReleaseVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateReleaseVersion in interface VersionService

Parameters:

user - The user trying to release a version

version - The version to release

releaseDate - The version release date (optional)

Returns:

ReleaseVersionValidationResult object

validateUnreleaseVersion

@Nonnull
public VersionService.ReleaseVersionValidationResult validateUnreleaseVersion(@Nullable
                                                                                       ApplicationUser user,
                                                                                       @Nonnull
                                                                                       Version version,
                                                                                       @Nullable
                                                                                       Date releaseDate)

Description copied from interface: VersionService

This method needs to be called before unreleasing a version to ensure all parameters are correct. There is required parameter, version object. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version provided has a valid name and if is released already.

The method will return a VersionService.ReleaseVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateUnreleaseVersion in interface VersionService

Parameters:

user - The user trying to unrelease a version

version - The version to release

releaseDate - The version release date (optional)

Returns:

ReleaseVersionValidationResult object

validateUnreleaseVersion

@Nonnull
public VersionService.ReleaseVersionValidationResult validateUnreleaseVersion(@Nullable
                                                                                       ApplicationUser user,
                                                                                       @Nonnull
                                                                                       Version version,
                                                                                       @Nonnull
                                                                                       String releaseDate)

Description copied from interface: VersionService

This method needs to be called before unreleasing a version to ensure all parameters are correct. There is required parameter, version object. An error will be returned if the user making the request does not have the ADMIN or PROJECT_ADMIN permission for the project. The validation will also check if a version provided has a valid name and if is released already.

The method will return a VersionService.ReleaseVersionValidationResult which contains an ErrorCollection with any potential errors and all the version's details.

Specified by:

validateUnreleaseVersion in interface VersionService

Parameters:

user - The user trying to unrelease a version

version - The version to release

releaseDate - The version release date (optional)

Returns:

ReleaseVersionValidationResult object

validateArchiveVersion

@Nonnull
public VersionService.ArchiveVersionValidationResult validateArchiveVersion(@Nullable
                                                                                     ApplicationUser user,
                                                                                     @Nonnull
                                                                                     Version version)

Description copied from interface: VersionService

This method should be called before archiving a version. It performs some basic validation of the version that was passed in. This includes a null check, checking that the version name isn't empty, and checking that the version is linked against a valid project.

The method also validates that the user passed in is either a global admin, or has project admin rights for the project that the version is linked to.

Finally, this method checks that the version that was passed in hasn't already been archived. If there's any errors, the validationResult will contain appropriate errors and wont be valid.

Specified by:

validateArchiveVersion in interface VersionService

Parameters:

user - The user performing this operation

version - The version to be archived

Returns:

a validation result, containing any errors or the version details on success

validateUnarchiveVersion

@Nonnull
public VersionService.ArchiveVersionValidationResult validateUnarchiveVersion(@Nullable
                                                                                       ApplicationUser user,
                                                                                       @Nonnull
                                                                                       Version version)

Description copied from interface: VersionService

This method should be called before unarchiving a version. It performs some basic validation of the version that was passed in. This includes a null check, checking that the version name isn't empty, and checking that the version is linked against a valid project.

The method also validates that the user passed in is either a global admin, or has project admin rights for the project that the version is linked to.

Finally, this method checks that the version that was passed is currently archived. If there's any errors, the validationResult will contain appropriate errors and wont be valid.

Specified by:

validateUnarchiveVersion in interface VersionService

Parameters:

user - The user performing this operation

version - The version to be archived

Returns:

a validation result, containing any errors or the version details on success

releaseVersion

public Version releaseVersion(VersionService.ReleaseVersionValidationResult result)

Description copied from interface: VersionService

Using the validation result from #validateReleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be released. This method will throw an IllegalArgumentException if the provied data are invalid and version could not be released.

Specified by:

releaseVersion in interface VersionService

Parameters:

result - a ReleaseVersionValidationResult containg required data

Returns:

a released version object

moveUnreleasedToNewVersion

public void moveUnreleasedToNewVersion(@Nullable
                                       ApplicationUser directoryUser,
                                       @Nonnull
                                       Version currentVersion,
                                       @Nonnull
                                       Version newVersion)

Description copied from interface: VersionService

Using the validation result from #validateReleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be released. This method will throw an IllegalArgumentException if the provided data are invalid and version could not be released.

Specified by:

moveUnreleasedToNewVersion in interface VersionService

Parameters:

directoryUser - The user trying to release a version

currentVersion - The current version being released.

newVersion - The version to move issues to.

unreleaseVersion

public Version unreleaseVersion(VersionService.ReleaseVersionValidationResult result)

Description copied from interface: VersionService

Using the validation result from #validateUnreleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be unreleased. This method will throw an IllegalArgumentException if the provied data are invalid and version could not be unreleased.

Specified by:

unreleaseVersion in interface VersionService

Parameters:

result - a ReleaseVersionValidationResult containg required data

Returns:

a unreleased version object

archiveVersion

public Version archiveVersion(VersionService.ArchiveVersionValidationResult result)

Description copied from interface: VersionService

Takes a validation result and performs the archive operation.

Specified by:

archiveVersion in interface VersionService

Parameters:

result - The result from the validation

Returns:

The version that was archived. Ideally this version should have been retrieved from the store for consistency

unarchiveVersion

public Version unarchiveVersion(VersionService.ArchiveVersionValidationResult result)

Description copied from interface: VersionService

Takes a validation result and performs the unarchive operation.

Specified by:

unarchiveVersion in interface VersionService

Parameters:

result - The result from the validation

Returns:

The version that was unarchived. Ideally this version should have been retrieved from the store for consistency

validateMoveToStartVersionSequence

@Nonnull
public VersionService.MoveVersionValidationResult validateMoveToStartVersionSequence(@Nullable
                                                                                              ApplicationUser user,
                                                                                              long versionId)

Description copied from interface: VersionService

Validate Move a version to the start of the version list.

Specified by:

validateMoveToStartVersionSequence in interface VersionService

Parameters:

user - The user trying to move a version

Returns:

a validation result, containing any errors or the version details on success

validateIncreaseVersionSequence

@Nonnull
public VersionService.MoveVersionValidationResult validateIncreaseVersionSequence(@Nullable
                                                                                           ApplicationUser user,
                                                                                           long versionId)

Description copied from interface: VersionService

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

Specified by:

validateIncreaseVersionSequence in interface VersionService

Parameters:

user - The user trying to move a version

Returns:

a validation result, containing any errors or the version details on success

validateDecreaseVersionSequence

@Nonnull
public VersionService.MoveVersionValidationResult validateDecreaseVersionSequence(@Nullable
                                                                                           ApplicationUser user,
                                                                                           long versionId)

Description copied from interface: VersionService

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

Specified by:

validateDecreaseVersionSequence in interface VersionService

Parameters:

user - The user trying to move a version

Returns:

a validation result, containing any errors or the version details on success

validateMoveToEndVersionSequence

@Nonnull
public VersionService.MoveVersionValidationResult validateMoveToEndVersionSequence(@Nullable
                                                                                            ApplicationUser user,
                                                                                            long versionId)

Description copied from interface: VersionService

Validate Move a version to the end of the version sequence.

Specified by:

validateMoveToEndVersionSequence in interface VersionService

Parameters:

user - The user trying to move a version

Returns:

a validation result, containing any errors or the version details on success

validateMoveVersionAfter

@Nonnull
public VersionService.MoveVersionValidationResult validateMoveVersionAfter(@Nullable
                                                                                    ApplicationUser user,
                                                                                    long versionId,
                                                                                    @Nonnull
                                                                                    Long scheduleAfterVersionId)

Description copied from interface: VersionService

Validate Move a version after another version.

Specified by:

validateMoveVersionAfter in interface VersionService

Parameters:

user - The user trying to move a version

versionId - version to reschedule

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

Returns:

a validation result, containing any errors or the version details and schedule after target on success

moveToStartVersionSequence

public void moveToStartVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult)

Description copied from interface: VersionService

Move a version to the start of the version list.

Specified by:

moveToStartVersionSequence in interface VersionService

Parameters:

moveVersionValidationResult - Move Version Validation Result

increaseVersionSequence

public void increaseVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult)

Description copied from interface: VersionService

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

Specified by:

increaseVersionSequence in interface VersionService

Parameters:

moveVersionValidationResult - Move Version Validation Result

decreaseVersionSequence

public void decreaseVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult)

Description copied from interface: VersionService

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

Specified by:

decreaseVersionSequence in interface VersionService

Parameters:

moveVersionValidationResult - Move Version Validation Result

moveToEndVersionSequence

public void moveToEndVersionSequence(VersionService.MoveVersionValidationResult moveVersionValidationResult)

Description copied from interface: VersionService

Move a version to the end of the version sequence.

Specified by:

moveToEndVersionSequence in interface VersionService

Parameters:

moveVersionValidationResult - Move Version Validation Result

moveVersionAfter

public void moveVersionAfter(VersionService.MoveVersionValidationResult moveVersionValidationResult)

Description copied from interface: VersionService

Move a version after another version.

Specified by:

moveVersionAfter in interface VersionService

Parameters:

moveVersionValidationResult - Move Version Validation Result

isOverdue

public boolean isOverdue(Version version)

Description copied from interface: VersionService

Is the passed version overdue? This method does no permission checks on the passed version.

Specified by:

isOverdue in interface VersionService

Parameters:

version - the version to check.

Returns:

true if the passed version is overdue.

getFixIssuesCount

public long getFixIssuesCount(Version version)

Description copied from interface: VersionService

Return the count of Issues Fixed in this version.

Specified by:

getFixIssuesCount in interface VersionService

Returns:

A count of issues

getAffectsIssuesCount

public long getAffectsIssuesCount(Version version)

Description copied from interface: VersionService

Return the count of Issues that have the "Affects Version" field set to version.

Specified by:

getAffectsIssuesCount in interface VersionService

Returns:

A count of issues

getCustomFieldsUsing

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

Description copied from interface: VersionService

This method returns usage information in custom fields for a given version.

Specified by:

getCustomFieldsUsing in interface VersionService

Parameters:

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

Returns:

collection of version usage for each custom fields.

getCustomFieldIssuesCount

public long getCustomFieldIssuesCount(@Nonnull
                                      Version version)

Description copied from interface: VersionService

This method returns the total number of issues where this version is used in custom fields

Specified by:

getCustomFieldIssuesCount in interface VersionService

Parameters:

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

Returns:

collection of version usage for each custom fields.

getUnresolvedIssuesCount

public long getUnresolvedIssuesCount(@Nullable
                                     ApplicationUser user,
                                     @Nonnull
                                     Version version)

Description copied from interface: VersionService

Return the count of Issues that are unresolved in this version. Used when releasing a version to get user confirmation about what to do with the unresolved issues.

Specified by:

getUnresolvedIssuesCount in interface VersionService

Parameters:

user - the user trying to get the count

version - which version to check for unresolved issues

Returns:

A count of issues

validateCreate

@Nonnull
public VersionService.VersionBuilderValidationResult validateCreate(@Nullable
                                                                             ApplicationUser user,
                                                                             @Nonnull
                                                                             VersionBuilder versionBuilder)

Description copied from interface: VersionService

Validates the creation of a new Version object, specified with a VersionBuilder.

This replaces the deprecated methods: #validateCreateVersion(User, Project, String, Date, String, Long) and #validateCreateVersion(User, Project, String, String, String, Long).

Specified by:

validateCreate in interface VersionService

Parameters:

user - the user who is performing the create

versionBuilder - the builder which specified the new Version to be created

Returns:

the result

See Also:

VersionService.newVersionBuilder()

create

@Nonnull
public ServiceOutcome<Version> create(@Nullable
                                               ApplicationUser user,
                                               @Nonnull
                                               VersionService.VersionBuilderValidationResult validationResult)

Description copied from interface: VersionService

Creates a new Version, based on the validation result from calling #validateCreate(User, VersionBuilder).

Specified by:

create in interface VersionService

Parameters:

user - the user

validationResult - the result of validation

Returns:

the new Version object; errors if not successful.

See Also:

#validateCreate(com.atlassian.crowd.embedded.api.User, VersionBuilder), #validateCreate(com.atlassian.crowd.embedded.api.User, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder)

newVersionBuilder

public VersionBuilder newVersionBuilder(Version version)

Description copied from interface: VersionService

Creates a builder to be used when updating an existing Version. The builder encapsulates all the fields which need to be specified on update.

Specified by:

newVersionBuilder in interface VersionService

Parameters:

version - the Version object to update

Returns:

the builder instance

See Also:

for creating a new version, for creating a new version

newVersionBuilder

public VersionBuilder newVersionBuilder()

Description copied from interface: VersionService

Creates a builder to be used when creating a new Version. The builder encapsulates all the fields which need to be specified on create.

Specified by:

newVersionBuilder in interface VersionService

Returns:

the builder instance

See Also:

for updating an existing version, for updating an existing version

validateUpdate

@Nonnull
public VersionService.VersionBuilderValidationResult validateUpdate(@Nullable
                                                                             ApplicationUser user,
                                                                             @Nonnull
                                                                             VersionBuilder versionBuilder)

Description copied from interface: VersionService

Validates the update of an existing Version object, specified with a VersionBuilder.

This replaces the deprecated methods: #validateReleaseDate(User, Version, String) and #validateVersionDetails(User, Version, String, String).

Specified by:

validateUpdate in interface VersionService

Parameters:

user - the user who is performing the update

versionBuilder - the builder which specified the update to the existing Version

Returns:

the result

See Also:

VersionService.newVersionBuilder(com.atlassian.jira.project.version.Version), #newBuilder(com.atlassian.jira.project.version.Version)

update

public ServiceOutcome<Version> update(ApplicationUser user,
                                      VersionService.VersionBuilderValidationResult validationResult)

Description copied from interface: VersionService

Updates the existing Version, based on the validation result from calling #validateUpdate(User, VersionBuilder).

Specified by:

update in interface VersionService

Parameters:

user - the user

validationResult - the result of validation

Returns:

the updated Version object; errors if not successful.

See Also:

#validateUpdate(com.atlassian.crowd.embedded.api.User, VersionBuilder), #validateUpdate(com.atlassian.crowd.embedded.api.User, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder)

getVersionsByProject

public ServiceOutcome<Page<Version>> getVersionsByProject(@Nullable
                                                          ApplicationUser user,
                                                          @Nonnull
                                                          Project project,
                                                          @Nonnull
                                                          PageRequest pageRequest,
                                                          io.atlassian.fugue.Option<OrderByRequest<VersionService.VersionExtractableField>> orderBy)

parseDate

@Nullable
protected Date parseDate(@Nullable
                                   ApplicationUser user,
                                   com.atlassian.jira.bc.project.version.DefaultVersionService.DateField field,
                                   String date)
                            throws com.atlassian.jira.bc.project.version.DefaultVersionService.DateParseException

Parses a string release date into a Date object, throwing an exception if there is a problem parsing the string. If the release date is an empty string, this method returns null.

Parameters:

user - the user who has provided the date

field - a DateField instance containing information what kind of date we are parsing

date - a string containing a date

Returns:

a Date object, or null

Throws:

com.atlassian.jira.bc.project.version.DefaultVersionService.DateParseException - if there is a problem parsing the date string

validateStartReleaseDates

protected ServiceOutcome<Void> validateStartReleaseDates(ApplicationUser user,
                                                         com.atlassian.jira.bc.project.version.DefaultVersionService.DateField field,
                                                         Date startDate,
                                                         Date releaseDate)