com.atlassian.jira.bc.project.version
Interface VersionService

All Known Implementing Classes:
DefaultVersionService

public interface VersionService

Service for VersionService

Since:
v3.13

Nested Class Summary
static class VersionService.AbstractVersionResult
           
static class VersionService.ArchiveVersionValidationResult
           
static class VersionService.CreateVersionValidationResult
           
static class VersionService.ReleaseVersionValidationResult
           
static interface VersionService.ValidationResult
          Represents the results of performing a validation call for a single merge or delete operation.
static interface VersionService.VersionAction
           
static class VersionService.VersionResult
           
static class VersionService.VersionsResult
           
 
Field Summary
static VersionService.VersionAction REMOVE
          Indicates that the Version should be removed from affected issues.
 
Method Summary
 Version archiveVersion(VersionService.ArchiveVersionValidationResult result)
          Takes a validation result and performs the archive operation.
 Version createVersion(com.opensymphony.user.User user, VersionService.CreateVersionValidationResult request)
          Using the validation result from validateCreateVersion(com.opensymphony.user.User, com.atlassian.jira.project.Project, String, String, String, Long) a new version will be created.
 void delete(JiraServiceContext context, VersionService.ValidationResult result)
          Deletes a version from a project.
 VersionService.VersionResult getVersionById(com.opensymphony.user.User user, java.lang.Long versionId)
          Used to retrieve a Version object by version id.
 VersionService.VersionResult getVersionById(com.opensymphony.user.User user, Project project, java.lang.Long versionId)
          Used to retrieve a Version object by version id within project specified by Project object.
 VersionService.VersionResult getVersionByProjectAndName(com.opensymphony.user.User user, Project project, java.lang.String versionName)
          Used to retrieve a Version object by version name within project specified by Project object.
 VersionService.VersionsResult getVersionsByProject(com.opensymphony.user.User user, Project project)
          Used to retrieve a Version collection within project specified by Project object.
 void merge(JiraServiceContext context, VersionService.ValidationResult result)
          Merges a version into another, then removes the original version.
 Version releaseVersion(VersionService.ReleaseVersionValidationResult result)
          Using the validation result from validateReleaseVersion(com.opensymphony.user.User, com.atlassian.jira.project.version.Version, Date) a version will be released.
 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(com.opensymphony.user.User, com.atlassian.jira.project.version.Version, Date) a version will be unreleased.
 VersionService.ArchiveVersionValidationResult validateArchiveVersion(com.opensymphony.user.User user, Version version)
          This method should be called before archiving a version.
 VersionService.CreateVersionValidationResult validateCreateVersion(com.opensymphony.user.User user, Project project, java.lang.String versionName, java.lang.String releaseDate, java.lang.String description, java.lang.Long scheduleAfterVersion)
          This method needs to be called before creating a version to ensure all parameters are correct.
 VersionService.ValidationResult validateDelete(JiraServiceContext context, java.lang.Long versionId, VersionService.VersionAction affectsAction, VersionService.VersionAction fixAction)
          Validates an attempt to delete a version from a project.
 VersionService.ValidationResult validateMerge(JiraServiceContext context, java.lang.Long versionId, java.lang.Long swapVersionId)
          Validates an attempt to merge a version into another.
 VersionService.ReleaseVersionValidationResult validateReleaseVersion(com.opensymphony.user.User user, Version version, java.util.Date releaseDate)
          This method needs to be called before releasing a version to ensure all parameters are correct.
 VersionService.ArchiveVersionValidationResult validateUnarchiveVersion(com.opensymphony.user.User user, Version version)
          This method should be called before unarchiving a version.
 VersionService.ReleaseVersionValidationResult validateUnreleaseVersion(com.opensymphony.user.User user, Version version, java.util.Date releaseDate)
          This method needs to be called before unreleasing a version to ensure all parameters are correct.
 

Field Detail

REMOVE

static final VersionService.VersionAction REMOVE
Indicates that the Version should be removed from affected issues.

Method Detail

validateDelete

VersionService.ValidationResult validateDelete(JiraServiceContext context,
                                               java.lang.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 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

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

validateMerge

VersionService.ValidationResult validateMerge(JiraServiceContext context,
                                              java.lang.Long versionId,
                                              java.lang.Long swapVersionId)
Validates an attempt to merge a version into another. Merging is essentially the same as Deleting with the actions set to VersionKeys.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:
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

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

getVersionById

VersionService.VersionResult getVersionById(com.opensymphony.user.User user,
                                            Project project,
                                            java.lang.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

getVersionById

VersionService.VersionResult getVersionById(com.opensymphony.user.User user,
                                            java.lang.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
Since:
4.2

getVersionByProjectAndName

VersionService.VersionResult getVersionByProjectAndName(com.opensymphony.user.User user,
                                                        Project project,
                                                        java.lang.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:
VerionResult object

getVersionsByProject

VersionService.VersionsResult getVersionsByProject(com.opensymphony.user.User 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

validateCreateVersion

VersionService.CreateVersionValidationResult validateCreateVersion(com.opensymphony.user.User user,
                                                                   Project project,
                                                                   java.lang.String versionName,
                                                                   java.lang.String releaseDate,
                                                                   java.lang.String description,
                                                                   java.lang.Long scheduleAfterVersion)
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

createVersion

Version createVersion(com.opensymphony.user.User user,
                      VersionService.CreateVersionValidationResult request)
Using the validation result from validateCreateVersion(com.opensymphony.user.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 containg all required data
Returns:
created Version object

validateReleaseVersion

VersionService.ReleaseVersionValidationResult validateReleaseVersion(com.opensymphony.user.User user,
                                                                     Version version,
                                                                     java.util.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

validateUnreleaseVersion

VersionService.ReleaseVersionValidationResult validateUnreleaseVersion(com.opensymphony.user.User user,
                                                                       Version version,
                                                                       java.util.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

releaseVersion

Version releaseVersion(VersionService.ReleaseVersionValidationResult result)
Using the validation result from validateReleaseVersion(com.opensymphony.user.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

unreleaseVersion

Version unreleaseVersion(VersionService.ReleaseVersionValidationResult result)
Using the validation result from validateUnreleaseVersion(com.opensymphony.user.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

validateArchiveVersion

VersionService.ArchiveVersionValidationResult validateArchiveVersion(com.opensymphony.user.User 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

validateUnarchiveVersion

VersionService.ArchiveVersionValidationResult validateUnarchiveVersion(com.opensymphony.user.User 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

archiveVersion

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

unarchiveVersion

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


Copyright © 2002-2011 Atlassian. All Rights Reserved.