Package com.atlassian.greenhopper.service.sprint

Interface SprintService

All Known Implementing Classes:
SprintServiceImpl
@ExperimentalApi public interface SprintService
Service which provides method to access and manipulate Sprints.

Before each operation validation is performed and its result is returned in ServiceOutcome. During validation, parameters and user's permissions are checked. User param with null value is treated as non-logged user.

Since:
6.7

  • Method Details

    • getSprint

      @Nonnull ServiceOutcome<Sprint> getSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Long sprintId)
      Get a sprint given its id. The sprint is only returned if the user can see rapid view where the sprint was created or can see at least one of the issues assigned to the sprint.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      sprintId - the id of the requested sprint.
      Returns:
      a requested sprint or error if operation failed.

    • getSprints

      @Nonnull ServiceOutcome<Set<Sprint>> getSprints(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull RapidView rapidView, @Nonnull Set<Long> sprintIds)
      Get a set of sprints by id checking each for visibility permission.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      rapidView - the rapidView which contains sprints.
      sprintIds - the set of ids of requested sprints.
      Returns:
      a set of founded sprint or error if operation failed.

    • getSprints

      @Nonnull ServiceOutcome<Page<Sprint>> getSprints(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull RapidView rapidView, @Nonnull PageRequest pageRequest, @Nonnull SprintQuery query)
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      rapidView - the rapidView which contains sprints.
      pageRequest - information about the desired number of results and theirs offset.
      query - query which limits the result only to these sprints which fulfil its constraints.
      Returns:
      a page of sprints matching the query ordered by state and sequence number or error if operation has failed.

    • findSprintsByName

      @Nonnull ServiceOutcome<Set<Sprint>> findSprintsByName(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull String searchQuery, int maxResults, boolean excludeCompleted)
      Get a set of sprints matching a search query.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      searchQuery - the string to match sprint names against.
      excludeCompleted - whether to include completed sprints or not.
      Returns:
      a set of requested sprints or error if operation failed.

    • createSprint

      @Nonnull @Deprecated ServiceOutcome<Sprint> createSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull RapidView rapidView, @Nonnull Sprint sprintData, @Nonnull Set<com.atlassian.jira.issue.Issue> issues)
      Deprecated.
      Use createSprint(ApplicationUser, Sprint) instead. Since v6.7.
      Create a new sprint in a future state. The user needs to have Project Administrator permissions for all issues.

      Can only create sprint in future state.

      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      rapidView - the sprint's rapid view.
      sprintData - the sprint object to persist. Sprint name and rapidViewId are required. Start and end date are optional. Other fields are ignored.
      issues - the issues to include in the sprint.
      Returns:
      a created sprint or error if operation failed.

    • createSprint

      @Nonnull ServiceOutcome<Sprint> createSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprintData)
      Create a new sprint in a future state. The user needs to have Project Administrator permissions for all issues.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      sprintData - the sprint object to persist. Sprint name and rapidViewId are required. Start and end date are optional. Other fields are ignored.
      Returns:
      a created sprint or error if operation failed.

    • updateSprint

      @Nonnull ServiceOutcome<Sprint> updateSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprint)
      Update a sprint.

      When a sprints state is updated from active to complete, the completeDate is set to now.

      When a sprints state is updated from future to active, the activatedDate is set to now.

      To update a sprint to be in the active state, the start and end date must be set.

      Updating of state is restricted to active from future and closed from active.

      A sprint which is in a closed state cannot be updated.
      Parameters:
      user - the user who is performing operation and whose MANAGE_SPRINTS permissions are checked. Null means anonymous access.
      sprint - the sprint which will be updated. Which sprint will be updated is determined by its id.
      Returns:
      a updated sprint or error if operation failed.

    • startStopSprint

      @Nonnull ServiceOutcome<Sprint> startStopSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprint)
      Change a sprint's state. Requires either the START_STOP_SPRINTS permission or the MANAGE_SPRINTS permission.
      See Also:

    • reopenSprint

      @Nonnull ServiceOutcome<Sprint> reopenSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprint)
      Reopen a sprint. Only closed sprints can be reopened.

      When a sprints state is updated from complete to active, the completeDate is set to null.

      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      sprint - the sprint which will be reopened.
      Returns:
      a reopened sprint or error if operation failed.

    • swapSprints

      @Nonnull ServiceResult swapSprints(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprintA, @Nonnull Sprint sprintB)
      Swap two sprints' sequences.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      sprintA - the first sprint.
      sprintB - the second sprint.
      Returns:
      a service result which is either valid or contains error messages.

    • getLastCompletedSprint

      @Nonnull ServiceOutcome<io.atlassian.fugue.Option<Sprint>> getLastCompletedSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull RapidView rapidView)
      Get the last completed sprint
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      rapidView - the sprint's rapid view.
      Returns:
      a last completed sprint if it exist or error if user doesn't have permistion to perform this operation.

    • deleteSprint

      @Nonnull ServiceResult deleteSprint(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Sprint sprint, @Nullable Long rapidViewId)
      Delete a sprint.

      Only future sprints can be deleted. All issues are detached from the sprint and possibly moved to a next planned sprint.

      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      sprint - the sprint which will be deleted.
      rapidViewId - if rapid board id is provided, then incomplete issues from the sprint will be moved to the next sprint planned on the board with this id
      Returns:
      a service result which is either valid or contains error messages.

    • unmapSprints

      ServiceResult unmapSprints(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Collection<Sprint> sprints)
      Sets the synced flag on the given sprints to false. Note that this operation is not reversible.
      Parameters:
      user - the user who is performing the operation
      sprints - the sprints to unsync
      Returns:
      a service result which is either valid or contains error messages

    • unmapSprintIds

      ServiceResult unmapSprintIds(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull Collection<Long> sprintIds)
      Sets the synced flag on the given sprints to false. Note that this operation is not reversible.
      Parameters:
      user - the user who is performing the operation
      sprintIds - the ids of the sprints to unsync
      Returns:
      a service result which is either valid or contains error messages

    • unmapAllSprints

      ServiceResult unmapAllSprints(@Nullable com.atlassian.jira.user.ApplicationUser user)
      Sets the synced flag on all sprints to false. Note that this operation is not reversible.
      Parameters:
      user - the user who is performing the operation
      Returns:
      a service result which is either valid or contains error messages

    • findSprintsByNameAndRapidViews

      @Nonnull ServiceOutcome<Set<Sprint>> findSprintsByNameAndRapidViews(@Nullable com.atlassian.jira.user.ApplicationUser user, @Nonnull String searchQuery, @Nonnull Set<Long> rapidViewIds, int maxResults, boolean excludeCompleted)
      Get a set of sprints matching a search query and rapidViews. Sprint to be matched needs to be created on any given rapid view.
      Parameters:
      user - the user who is performing operation and whose permissions are checked. Null means anonymous access.
      searchQuery - the string to match sprint names against.
      rapidViewIds - set of RapidView ids where sprints were created.
      excludeCompleted - whether to include completed sprints or not.
      Returns:
      a set of requested sprints or error if operation failed.

    • validateSprintData

      @Nonnull ServiceResult validateSprintData(@Nonnull Sprint sprint)
      Validates sprint data against given conditions.
      Parameters:
      sprint - the sprint which data is being validated against given conditions
      Returns:
      an empty service result when all the validations passed, the list of validation errors otherwise