@PublicApi public interface

VersionService

com.atlassian.jira.bc.project.version.VersionService
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

Service for VersionService

Summary

Nested Classes
class VersionService.AbstractVersionResult  
class VersionService.ArchiveVersionValidationResult  
class VersionService.CreateVersionValidationResult  
class VersionService.MoveVersionValidationResult  
class VersionService.ReasonsServiceResult<R, T> A generified ServiceResultImpl that allows Service-specified Reasons to be set as part of the result (in addition to Reasons specified inside the ErrorCollection. 
class VersionService.ReleaseVersionValidationResult  
interface VersionService.ValidationResult Represents the results of performing a validation call for a single merge or delete operation. 
interface VersionService.VersionAction  
class VersionService.VersionBuilderValidationResult Result object that relates to new VersionService methods that take a VersionBuilder as a parameter. 
enum VersionService.VersionExtractableField  
class VersionService.VersionResult  
class VersionService.VersionsResult  
Fields
public static final VersionService.VersionAction REMOVE Indicates that the Version should be removed from affected issues.
Public Methods
Version archiveVersion(VersionService.ArchiveVersionValidationResult result)
Takes a validation result and performs the archive operation.
@Nonnull ServiceOutcome<Version> create(ApplicationUser user, VersionService.VersionBuilderValidationResult validationResult)
Creates a new Version, based on the validation result from calling #validateCreate(User, VersionBuilder).
@Deprecated Version createVersion(ApplicationUser user, VersionService.CreateVersionValidationResult request)
This method is deprecated. Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4
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.
long getAffectsIssuesCount(Version version)
Return the count of Issues that affect this 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.
@Nonnull VersionService.VersionResult getVersionByProjectAndName(ApplicationUser user, Project project, String versionName)
Used to retrieve a Version object by version name within project specified by Project object.
@Nonnull ServiceOutcome<Page<Version>> getVersionsByProject(ApplicationUser user, Project project, PageRequest pageRequest, OrderByRequest<VersionService.VersionExtractableField> orderBy)
This method returns all versions for a given project.
@Nonnull VersionService.VersionsResult getVersionsByProject(ApplicationUser user, Project project)
Used to retrieve a Version collection within project specified by Project object.
@Nonnull ServiceOutcome<Page<Version>> getVersionsByProject(ApplicationUser user, Project project, PageRequest pageRequest)
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 user, 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(Version version)
Creates a builder to be used when updating an existing Version.
VersionBuilder newVersionBuilder()
Creates a builder to be used when creating a new Version.
Version releaseVersion(VersionService.ReleaseVersionValidationResult result)
Using the validation result from #validateReleaseVersion(User, com.atlassian.jira.project.version.Version, Date) a version will be released.
@Deprecated ServiceOutcome<Version> setReleaseDate(ApplicationUser user, Version version, Date releaseDate)
This method is deprecated. Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4
@Deprecated ServiceOutcome<Version> setReleaseDate(ApplicationUser user, Version version, String releaseDate)
This method is deprecated. Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4
@Deprecated ServiceOutcome<Version> setVersionDetails(ApplicationUser user, Version version, String name, String description)
This method is deprecated. Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4
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).
@Nonnull VersionService.ArchiveVersionValidationResult validateArchiveVersion(ApplicationUser user, Version version)
This method should be called before archiving a version.
@Nonnull VersionService.VersionBuilderValidationResult validateCreate(ApplicationUser user, VersionBuilder versionBuilder)
Validates the creation of a new Version object, specified with a VersionBuilder.
@Deprecated VersionService.CreateVersionValidationResult validateCreateVersion(ApplicationUser user, Project project, String versionName, Date releaseDate, String description, Long scheduleAfterVersion)
This method is deprecated. Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4
@Deprecated VersionService.CreateVersionValidationResult validateCreateVersion(ApplicationUser user, Project project, String versionName, String releaseDate, String description, Long scheduleAfterVersion)
This method is deprecated. Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4.
@Nonnull 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.
@Nonnull 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)
Validates an attempt to merge a version into another.
@Nonnull VersionService.MoveVersionValidationResult validateMoveToEndVersionSequence(ApplicationUser user, long versionId)
Validate Move a version to the end of the version sequence.
@Nonnull 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 scheduleAfterVersion)
Validate Move a version after another version.
@Deprecated ServiceOutcome<Version> validateReleaseDate(ApplicationUser user, Version version, String releaseDate)
This method is deprecated. Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4
@Nonnull 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.
@Nonnull 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.
@Nonnull VersionService.ArchiveVersionValidationResult validateUnarchiveVersion(ApplicationUser user, Version version)
This method should be called before unarchiving a version.
@Nonnull 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.
@Nonnull 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.
@Nonnull VersionService.VersionBuilderValidationResult validateUpdate(ApplicationUser user, VersionBuilder versionBuilder)
Validates the update of an existing Version object, specified with a VersionBuilder.
@Deprecated ErrorCollection validateVersionDetails(ApplicationUser user, Version version, String name, String description)
This method is deprecated. Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

Fields

public static final VersionService.VersionAction REMOVE

Indicates that the Version should be removed from affected issues.

Public Methods

public Version archiveVersion (VersionService.ArchiveVersionValidationResult result)

Takes a validation result and performs the archive operation.

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
Throws
IllegalStateException if the result passed in is not valid.

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

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

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)

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

This method is deprecated.
Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4

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.

Parameters
user The user trying to get a version
request The VersionService.CreateVersionValidationResult object containing all required data
Returns
  • created Version object

public void decreaseVersionSequence (VersionService.MoveVersionValidationResult moveVersionValidationResult)

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

Parameters
moveVersionValidationResult Move Version Validation Result

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

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.

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

public long getAffectsIssuesCount (Version version)

Return the count of Issues that affect this version.

Returns
  • A count of issues

public long getFixIssuesCount (Version version)

Return the count of Issues Fixed in this version.

Returns
  • A count of issues

public long getUnresolvedIssuesCount (ApplicationUser user, Version version)

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.

Parameters
user the user trying to get the count
version which version to check for unresolved issues
Returns
  • A count of issues

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

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.

Parameters
user The user trying to get a version
versionId The id of requested version
Returns
  • VersionResult object

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

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.

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

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

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.

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

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

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.

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

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

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.

Parameters
user The user trying to get a version
project The project object containing requested version
Returns
  • VerionsResult object

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

This method returns all versions for a given project. It's similar to the 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.

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

public void increaseVersionSequence (VersionService.MoveVersionValidationResult moveVersionValidationResult)

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

Parameters
moveVersionValidationResult Move Version Validation Result

public boolean isOverdue (Version version)

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

Parameters
version the version to check.
Returns
  • true if the passed version is overdue.

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

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

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

public void moveToEndVersionSequence (VersionService.MoveVersionValidationResult moveVersionValidationResult)

Move a version to the end of the version sequence.

Parameters
moveVersionValidationResult Move Version Validation Result

public void moveToStartVersionSequence (VersionService.MoveVersionValidationResult moveVersionValidationResult)

Move a version to the start of the version list.

Parameters
moveVersionValidationResult Move Version Validation Result

public void moveUnreleasedToNewVersion (ApplicationUser user, Version currentVersion, Version newVersion)

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.

Parameters
user The user trying to release a version
currentVersion The current version being released.
newVersion The version to move issues to.

public void moveVersionAfter (VersionService.MoveVersionValidationResult moveVersionValidationResult)

Move a version after another version.

Parameters
moveVersionValidationResult Move Version Validation Result

public VersionBuilder newVersionBuilder (Version version)

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

Parameters
version the Version object to update
Returns
  • the builder instance
See Also

public VersionBuilder newVersionBuilder ()

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

Returns
  • the builder instance
See Also

public Version releaseVersion (VersionService.ReleaseVersionValidationResult result)

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.

Parameters
result a ReleaseVersionValidationResult containg required data
Returns
  • a released version object

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

This method is deprecated.
Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

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

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

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

This method is deprecated.
Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

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

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

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

This method is deprecated.
Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

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

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
Throws
IllegalArgumentException if the name is null or duplicates an existing name

public Version unarchiveVersion (VersionService.ArchiveVersionValidationResult result)

Takes a validation result and performs the unarchive operation.

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
Throws
IllegalStateException if the result passed in is not valid.

public Version unreleaseVersion (VersionService.ReleaseVersionValidationResult result)

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.

Parameters
result a ReleaseVersionValidationResult containg required data
Returns
  • a unreleased version object

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

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

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)

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

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.

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

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

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

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

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

This method is deprecated.
Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4

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.

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

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

This method is deprecated.
Use #validateCreate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder) and create(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilderValidationResult). Since v6.4.

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.

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

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

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

Parameters
user The user trying to move a version
Returns
  • a validation result, containing any errors or the version details on success

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

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.

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 REMOVE_ACTION, SWAP_ACTION
fixAction Used to decide wether to move all the issues to a different 'fix' version or just remove them. See REMOVE_ACTION, SWAP_ACTION
Returns

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

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

Parameters
user The user trying to move a version
Returns
  • a validation result, containing any errors or the version details on success

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

Validates an attempt to merge a version into another. Merging is essentially the same as Deleting with the actions set to SWAP_ACTION.

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

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

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

Parameters
user The user trying to move a version
Returns
  • a validation result, containing any errors or the version details on success

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

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

Parameters
user The user trying to move a version
Returns
  • a validation result, containing any errors or the version details on success

public VersionService.MoveVersionValidationResult validateMoveVersionAfter (ApplicationUser user, long versionId, Long scheduleAfterVersion)

Validate Move a version after another version.

Parameters
user The user trying to move a version
versionId version to reschedule
scheduleAfterVersion 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

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

This method is deprecated.
Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

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

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

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

Parameters
user The user trying to release a version
version The version to release
releaseDate The version release date (optional)
Returns
  • ReleaseVersionValidationResult object

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

Parameters
user The user trying to release a version
version The version to release
releaseDate The version release date (optional)
Returns
  • ReleaseVersionValidationResult object

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

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.

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

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

Parameters
user The user trying to unrelease a version
version The version to release
releaseDate The version release date (optional)
Returns
  • ReleaseVersionValidationResult object

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

Parameters
user The user trying to unrelease a version
version The version to release
releaseDate The version release date (optional)
Returns
  • ReleaseVersionValidationResult object

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

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

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

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

This method is deprecated.
Use #validateUpdate(com.atlassian.jira.user.ApplicationUser, com.atlassian.jira.bc.project.version.VersionService.VersionBuilder). Since v6.4

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

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
Throws
IllegalArgumentException if the name is null or duplicates an existing name