com.atlassian.jira.bc.issue.label
Interface LabelService

All Known Implementing Classes:
DefaultLabelService

@PublicApi
public interface LabelService

The label service is responsible for setting and getting labels for issue and custom field combinations. It can also be used to add and remove individual labels from an isssue.

Since:
v4.2

Nested Class Summary
static class LabelService.AddLabelValidationResult
           
static class LabelService.LabelsResult
           
static class LabelService.LabelSuggestionResult
           
static class LabelService.LabelValidationResult
           
static class LabelService.SetLabelValidationResult
           
 
Method Summary
 LabelService.LabelsResult addLabel(com.atlassian.crowd.embedded.api.User user, LabelService.AddLabelValidationResult result, boolean sendNotification)
          Adds the label to the issue specified by the validation result.
 LabelService.LabelsResult getLabels(com.atlassian.crowd.embedded.api.User user, Long issueId)
          Returns all the labels for the given issue.
 LabelService.LabelsResult getLabels(com.atlassian.crowd.embedded.api.User user, Long issueId, Long customFieldId)
          Returns all the labels for the given issue and custom field.
 LabelService.LabelSuggestionResult getSuggestedLabels(com.atlassian.crowd.embedded.api.User user, Long issueId, Long customFieldId, String token)
          Given a token to search for, this method returns a number of suggestions for the label.
 LabelService.LabelSuggestionResult getSuggestedLabels(com.atlassian.crowd.embedded.api.User user, Long issueId, String token)
          Given a token to search for, this method returns a number of suggestions for the label.
 LabelService.LabelsResult setLabels(com.atlassian.crowd.embedded.api.User user, LabelService.SetLabelValidationResult result, boolean sendNotification, boolean causeChangeNotification)
          Sets the labels for a particular issue to the set specified as a parameter.
 LabelService.AddLabelValidationResult validateAddLabel(com.atlassian.crowd.embedded.api.User user, Long issueId, Long customFieldId, String label)
          Validates that the user provided can add the label provided for a particular issue.
 LabelService.AddLabelValidationResult validateAddLabel(com.atlassian.crowd.embedded.api.User user, Long issueId, String label)
          Validates that the user provided can add the label provided for a particular issue.
 LabelService.SetLabelValidationResult validateSetLabels(com.atlassian.crowd.embedded.api.User user, Long issueId, Long customFieldId, Set<String> labels)
          Validates that the user provided can set the labels provided for a particular issue.
 LabelService.SetLabelValidationResult validateSetLabels(com.atlassian.crowd.embedded.api.User user, Long issueId, Set<String> labels)
          Validates that the user provided can set the labels provided for a particular issue.
 

Method Detail

getLabels

LabelService.LabelsResult getLabels(com.atlassian.crowd.embedded.api.User user,
                                    Long issueId)
Returns all the labels for the given issue.

Parameters:
user - The user performing the operation
issueId - The issue id that the label is linked against
Returns:
A set of alphabetically ordered labels for the issue.

validateSetLabels

LabelService.SetLabelValidationResult validateSetLabels(com.atlassian.crowd.embedded.api.User user,
                                                        Long issueId,
                                                        Set<String> labels)
Validates that the user provided can set the labels provided for a particular issue. Validation will ensure that the user has the EDIT_ISSUE permission for the issue in question. The labels will also be validated to ensure that they don't contain spaces and that they don't exceed the max length of 255 characters each.

Parameters:
user - The user performing the operation
issueId - The issue id of the issue that labels will be set on
labels - The actual labels as strings to set on the issue
Returns:
A validation result, that can be used to set the labels or to display errors.

validateSetLabels

LabelService.SetLabelValidationResult validateSetLabels(com.atlassian.crowd.embedded.api.User user,
                                                        Long issueId,
                                                        Long customFieldId,
                                                        Set<String> labels)
Validates that the user provided can set the labels provided for a particular issue. Validation will ensure that the user has the EDIT_ISSUE permission for the issue in question. The labels will also be validated to ensure that they don't contain spaces and that they don't exceed the max length of 255 characters each. Validation will also ensure that the custom field with the id provided exists.

Parameters:
user - The user performing the operation
issueId - The issue id of the issue that labels will be set on
customFieldId - The custom field id against which to set the labels
labels - The actual labels as strings to set on the issue
Returns:
A validation result, that can be used to set the labels or to display errors.

getLabels

LabelService.LabelsResult getLabels(com.atlassian.crowd.embedded.api.User user,
                                    Long issueId,
                                    Long customFieldId)
Returns all the labels for the given issue and custom field. The custom field may also be null, in which case the labels for the system field will be returned.

Parameters:
user - The user performing the operation
issueId - The issue id that the label is linked against
customFieldId - Custom field id for the labels CF or null if it's the system field.
Returns:
A set of alphabetically ordered labels for the issue and custom field.

setLabels

LabelService.LabelsResult setLabels(com.atlassian.crowd.embedded.api.User user,
                                    LabelService.SetLabelValidationResult result,
                                    boolean sendNotification,
                                    boolean causeChangeNotification)
Sets the labels for a particular issue to the set specified as a parameter. The set may be an empty set in order to clear all labels for an issue.

Parameters:
user - The user performing the operation
result - The validation result obtained by calling validateSetLabels(User, Long, java.util.Set)
sendNotification - true if a notification e-mail should be sent, false otherwise
causeChangeNotification - true if a change history should be created, false otherwise
Returns:
a set of stored label objects in alphabetical order

validateAddLabel

LabelService.AddLabelValidationResult validateAddLabel(com.atlassian.crowd.embedded.api.User user,
                                                       Long issueId,
                                                       String label)
Validates that the user provided can add the label provided for a particular issue. Validation will ensure that the user has the EDIT_ISSUE permission for the issue in question. The label will also be validated to ensure that it doesn't contain spaces and that it doesn't exceed the max length of 255 characters.

Parameters:
user - The user performing the operation
issueId - The issue id of the issue that labels will be set on
label - The actual labels as strings to set on the issue
Returns:
A validation result, that can be used to set the labels or to display errors.

validateAddLabel

LabelService.AddLabelValidationResult validateAddLabel(com.atlassian.crowd.embedded.api.User user,
                                                       Long issueId,
                                                       Long customFieldId,
                                                       String label)
Validates that the user provided can add the label provided for a particular issue. Validation will ensure that the user has the EDIT_ISSUE permission for the issue in question. The label will also be validated to ensure that it doesn't contain spaces and that it doesn't exceed the max length of 255 characters. Validation will also ensure that the custom field with the id provided exists.

Parameters:
user - The user performing the operation
issueId - The issue id of the issue that labels will be set on
customFieldId - Custom field id for the labels CF or null if it's the system field.
label - The actual labels as strings to set on the issue
Returns:
A validation result, that can be used to set the labels or to display errors.

addLabel

LabelService.LabelsResult addLabel(com.atlassian.crowd.embedded.api.User user,
                                   LabelService.AddLabelValidationResult result,
                                   boolean sendNotification)
Adds the label to the issue specified by the validation result.

Parameters:
user - The user performing the operation
result - The validation result obtained via validateAddLabel(User, Long, String)
sendNotification - true if a notification e-mail should be sent, false otherwise
Returns:
A result containing the new label.

getSuggestedLabels

LabelService.LabelSuggestionResult getSuggestedLabels(com.atlassian.crowd.embedded.api.User user,
                                                      Long issueId,
                                                      String token)
Given a token to search for, this method returns a number of suggestions for the label. The token may also be null or empty in which case a list of suggestions will be returned sorted by most popular labels for the labels system field. If a token was provided, then a list of labels sorted alphabetically starting with the token will be returned. If provided, any labels that the issue already has will be removed from the list of suggestions. The token needs to be at least 2 characters to generate suggestions starting with that token, otherwise an empty collection is returned.

Parameters:
user - The user trying to get label suggestions
issueId - The issue for which suggestions are being fetched or null
token - The prefix for the labels to be suggested. May be null for popular label suggestions
Returns:
suggestion result containing a set of suggestions either sorted alphabetically or by popularity depending on the token

getSuggestedLabels

LabelService.LabelSuggestionResult getSuggestedLabels(com.atlassian.crowd.embedded.api.User user,
                                                      Long issueId,
                                                      Long customFieldId,
                                                      String token)
Given a token to search for, this method returns a number of suggestions for the label. The token may also be null or empty in which case a list of suggestions will be returned sorted by most popular labels for the labels custom field provided. If a token was provided, then a list of labels sorted alphabetically starting with the token will be returned. If provided, any labels that the issue already has will be removed from the list of suggestions. The token needs to be at least 2 characters long to generate suggestions starting with that token, otherwise an empty collection is returned.

Parameters:
user - The user trying to get label suggestions
issueId - The issue for which suggestions are being fetched or null
customFieldId - The labels custom field for which to provide suggestions
token - The prefix for the labels to be suggested. May be null for popular label suggestions
Returns:
suggestion result containing a set of suggestions either sorted alphabetically or by popularity depending on the token


Copyright © 2002-2014 Atlassian. All Rights Reserved.