com.atlassian.confluence.labels
Interface LabelManager

All Known Implementing Classes:

DefaultLabelManager

public interface LabelManager

The label manager provides all that is necessary for interacting with labels.

Field Summary

static int	DEFAULT_LABEL_COUNT
static String	FAVOURITE_LABEL
static String	FAVOURITE_LABEL_YANKEE
static int	LABEL_ADDED Indicates that a label was added.
static int	LABEL_CREATED Indicates that a label was created.
static int	LABEL_DELETED Indicates that a label was deleted.
static int	LABEL_REMOVED Indicates that a label was removed.
static int	NO_CHANGE Indicates no change.

Method Summary

int	addLabel(ContentEntityObject content, Label label) Add a label to the specified content.
Label	createLabel(Label label)
boolean	deleteLabel(Label l) Delete the specified label.
boolean	deleteLabel(long id) Delete the label with the specified id.
List	getContent(Label label)
int	getContentCount(Label label)
List	getCurrentContentForLabel(Label label) Get all content associated with a label and space Get all current content associated with a label and any space.
List	getCurrentContentForLabelAndSpace(Label label, String spaceKey) Get all current content associated with a label and space.
List	getCurrentContentWithPersonalLabel(String username) Get all current content labelled by a user
List	getFavouriteSpaces(String username)
Label	getLabel(Label label) Retrieve the persistent instance of the label with the exact same details as the specified label.
Label	getLabel(long id) Retrieve the label with the specified id.
Label	getLabel(ParsedLabelName parsedLabelName) Retrieve the label by name.
Label	getLabel(String unparsedLabelName) convenience method to fetch a label without having to call the label parser
List	getLabelsByDetail(String labelName, String namespace, String spaceKey, String owner) Retrieves the labels matching the given labelName, namespace or owner
List	getLabelsInSpace(String key) Retrieve all of the labels that label content within the specified space.
List	getMostPopularLabels() Retrieve the list of the DEFAULT_LABEL_COUNT most popular labels within the system.
List	getMostPopularLabels(int maxResults) Retrieve the most popular labels within the system.
List	getMostPopularLabelsInSpace(String key) Retrieve the list of the DEFAULT_LABEL_COUNT most used labels in the specific space, ordered from most popular to least popular.
List	getMostPopularLabelsInSpace(String key, int maxResults) Retrieve a list of the 'n' most used labels in the specified space, ordered from most popular to least popular.
Set	getMostPopularLabelsWithRanks(Comparator comparator) Retrieve a set of the DEFAULT_LABEL_COUNT most popular labels within the system, including their ranks and ordered using the compartor provided.
Set	getMostPopularLabelsWithRanks(int maxResults, Comparator comparator) Retrieve the most popular labels within the system, including their ranks and ordered using the comparator provided.
Set	getMostPopularLabelsWithRanksInSpace(String key, int maxResults, Comparator comparator) Retrieve a set of the 'n' most used labels in the specified space, ordered using the compartor given.
List	getRecentlyUsedLabellings(int maxResults)
List	getRecentlyUsedLabellingsInSpace(String spaceKey, int maxResults)
List	getRecentlyUsedLabels() Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the system.
List	getRecentlyUsedLabels(int maxResults) Retrieve the x most recently used labels.
List	getRecentlyUsedLabelsInSpace(String spaceKey) Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the specified space.
List	getRecentlyUsedLabelsInSpace(String spaceKey, int maxResults) Retrieve the most recently used labels within the specified spae.
List	getRecentlyUsedPersonalLabellings(String username, int maxResults)
List	getRecentlyUsedPersonalLabels(String username) Retrieve the labels that were recently used by currently authenticated user.
List	getRecentlyUsedPersonalLabels(String username, int maxResults) Retrieve the labels that were recently used by currently authenticated user.
List	getRelatedLabels(Label label) Retrieve the DEFAULT_LABEL_COUNT labels that are 'related' to the specified label.
List	getRelatedLabels(Label label, int maxResults) Retrieve the labels that are 'related' to the specified label.
List	getRelatedLabelsInSpace(Label label, String spaceKey) Retrieve the DEFAULT_LABEL_COUNT labels that are 'related' to the specified label and that are used to label content within the specified space.
List	getRelatedLabelsInSpace(Label label, String spaceKey, int maxResults) Retrieve the labels that are 'related' to the specified label and that are used to to label content within the specified space.
List	getSpacesContainingContentWithLabel(Label label) Look up the spaces that have been labelled by the specific label.
List	getSpacesWithLabel(Label label) Spaces cannot be directly labelled.
List	getSuggestedLabels(ContentEntityObject content) Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content.
List	getSuggestedLabels(ContentEntityObject content, int maxResults) Retrieve the suggested labels for the specified content.
List	getSuggestedLabelsInSpace(ContentEntityObject content, String spaceKey) Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content bound to the specified space.
List	getSuggestedLabelsInSpace(ContentEntityObject content, String spaceKey, int maxResults) Retrieve the suggested labels for the specified content bound to the specified space.
List	getTeamLabels() Retrieve all of the team labels in the system.
List	getTeamLabelsForSpace(String spaceKey) Retrieve all of the team labels used to label content in the specified space.
List	getUsersLabels(String owner) Retrieve the personal labels that belong to the specified user.
void	removeAllLabels(ContentEntityObject content) Remove all of the labels from the specified content.
int	removeLabel(ContentEntityObject object, Label label) Remove a label from the specified content.
void	removeLabels(ContentEntityObject object, List labels)

Field Detail

FAVOURITE_LABEL

public static final String FAVOURITE_LABEL

See Also:

Constant Field Values

FAVOURITE_LABEL_YANKEE

public static final String FAVOURITE_LABEL_YANKEE

See Also:

Constant Field Values

DEFAULT_LABEL_COUNT

public static final int DEFAULT_LABEL_COUNT

See Also:

Constant Field Values

NO_CHANGE

public static final int NO_CHANGE

Indicates no change.

See Also:

addLabel(com.atlassian.confluence.core.ContentEntityObject, Label), removeLabel(com.atlassian.confluence.core.ContentEntityObject, Label), Constant Field Values

LABEL_ADDED

public static final int LABEL_ADDED

Indicates that a label was added.

See Also:

addLabel(com.atlassian.confluence.core.ContentEntityObject, Label), Constant Field Values

LABEL_CREATED

public static final int LABEL_CREATED

Indicates that a label was created.

See Also:

addLabel(com.atlassian.confluence.core.ContentEntityObject, Label), Constant Field Values

LABEL_REMOVED

public static final int LABEL_REMOVED

Indicates that a label was removed.

See Also:

removeLabel(com.atlassian.confluence.core.ContentEntityObject, Label), Constant Field Values

LABEL_DELETED

public static final int LABEL_DELETED

Indicates that a label was deleted.

See Also:

removeLabel(com.atlassian.confluence.core.ContentEntityObject, Label), Constant Field Values

Method Detail

addLabel

public int addLabel(ContentEntityObject content,
                    Label label)

Add a label to the specified content.

Note: the specified label does not need to be persistent. A persistent instance of the label will be created if necessary. eg: you can write code like: labelManager.addLabel(page, new Label("name", "namespace", "owner"));

Parameters:

content -

label -

Returns:

one of NO_CHANGE, LABEL_ADDED or LABEL_CREATED

removeLabel

public int removeLabel(ContentEntityObject object,
                       Label label)

Remove a label from the specified content.

Parameters:

object -

label -

Returns:

one of NO_CHANGE, LABEL_DELETED, LABEL_REMOVED

removeLabels

public void removeLabels(ContentEntityObject object,
                         List labels)

removeAllLabels

public void removeAllLabels(ContentEntityObject content)

Remove all of the labels from the specified content. Any labels that then no longer label content will be deleted.

Parameters:

content -

deleteLabel

public boolean deleteLabel(long id)

Delete the label with the specified id.

Parameters:

id -

Returns:

true if the label was deleted, false otherwise.

deleteLabel

public boolean deleteLabel(Label l)

Delete the specified label.

NOTE: The specified label does note need to be the persistent instance of the label, it simply needs to uniquely identify the label.

Parameters:

l -

Returns:

true if the label was deleted, false otherwise.

getLabel

public Label getLabel(long id)

Retrieve the label with the specified id.

Parameters:

id -

Returns:

the persistent instance of label with the specified id, or null if none exists.

getLabel

public Label getLabel(ParsedLabelName parsedLabelName)

Retrieve the label by name.

Parameters:

parsedLabelName -

Returns:

a persistent instance of the label or null if it can not be found.

See Also:

for details on the format of the labelReference parameter.

getLabel

public Label getLabel(String unparsedLabelName)

convenience method to fetch a label without having to call the label parser

Parameters:

unparsedLabelName - - example - my:foo

getLabel

public Label getLabel(Label label)

Retrieve the persistent instance of the label with the exact same details as the specified label. Note, the specified label does not need to contain an id.

Parameters:

label -

Returns:

a persistent instance of the label, or null if it does not exist.

getLabelsByDetail

public List getLabelsByDetail(String labelName,
                              String namespace,
                              String spaceKey,
                              String owner)

Retrieves the labels matching the given labelName, namespace or owner

Parameters:

labelName - The name of the label (null to ignore)

namespace - The namespace of the labels (null to ignore)

spaceKey - The spaceKey to restrict by (null to ignore)

owner - The owner of the labels (null to ignore)

Returns:

a list of Label instances

getLabelsInSpace

public List getLabelsInSpace(String key)

Retrieve all of the labels that label content within the specified space.

Parameters:

key - identifying the space to be queried.

Returns:

a list of labels that appear in the space.

getMostPopularLabels

public List getMostPopularLabels()

Retrieve the list of the DEFAULT_LABEL_COUNT most popular labels within the system.

Returns:

a list of label search result instances in order of their popularity.

See Also:

DefaultLabelManager.DEFAULT_LABEL_COUNT, LabelSearchResult

getMostPopularLabels

public List getMostPopularLabels(int maxResults)

Retrieve the most popular labels within the system. The number of labels returned can be specified through the count parameter. If the count value is greater than the number of labels, then all labels will be returned.

This function does not return the labels itself, but wrapped into a search result with a count!

Parameters:

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label search result instances in order of their popularity.

See Also:

LabelSearchResult

getMostPopularLabelsInSpace

public List getMostPopularLabelsInSpace(String key)

Retrieve the list of the DEFAULT_LABEL_COUNT most used labels in the specific space, ordered from most popular to least popular.

This function does not return the labels itself, but wrapped into a search result with a count!

Parameters:

key - the space key

Returns:

a list of label search result instances in order of their popularity.

See Also:

DefaultLabelManager.DEFAULT_LABEL_COUNT, LabelSearchResult

getMostPopularLabelsInSpace

public List getMostPopularLabelsInSpace(String key,
                                        int maxResults)

Retrieve a list of the 'n' most used labels in the specified space, ordered from most popular to least popular.

This function does not return the labels itself, but wrapped into a search result with a count!

Parameters:

key - is the space key

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label search result instances in order of their popularity.

See Also:

LabelSearchResult

getMostPopularLabelsWithRanks

public Set getMostPopularLabelsWithRanks(Comparator comparator)

Retrieve a set of the DEFAULT_LABEL_COUNT most popular labels within the system, including their ranks and ordered using the compartor provided.

Returns:

an ordered set of ranked label search result instances

See Also:

DefaultLabelManager.DEFAULT_LABEL_COUNT, RankedLabelSearchResult

getMostPopularLabelsWithRanks

public Set getMostPopularLabelsWithRanks(int maxResults,
                                         Comparator comparator)

Retrieve the most popular labels within the system, including their ranks and ordered using the comparator provided. The number of labels returned can be specified through the count parameter. If the count value is greater than the number of labels, then all labels will be returned.

This function does not return the labels itself, but wrapped into a search result with a count!

Parameters:

maxResults - is the maximum number of labels to be returned.

Returns:

an ordered set of ranked label search result instances

See Also:

RankedLabelSearchResult

getMostPopularLabelsWithRanksInSpace

public Set getMostPopularLabelsWithRanksInSpace(String key,
                                                int maxResults,
                                                Comparator comparator)

Retrieve a set of the 'n' most used labels in the specified space, ordered using the compartor given.

This function does not return the labels itself, but wrapped into a search result with a count!

Parameters:

key - is the space key

maxResults - is the maximum number of labels to be returned.

Returns:

an ordered set of rankded label search result instances

See Also:

RankedLabelSearchResult

getRecentlyUsedLabels

public List getRecentlyUsedLabels()

Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the system.

Returns:

a list of label instances in order of most recently used to least recently used.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getRecentlyUsedLabels

public List getRecentlyUsedLabels(int maxResults)

Retrieve the x most recently used labels.

Parameters:

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label instances in order of most recently used to least recently used.

getRecentlyUsedLabellings

public List getRecentlyUsedLabellings(int maxResults)

getRecentlyUsedLabelsInSpace

public List getRecentlyUsedLabelsInSpace(String spaceKey)

Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the specified space.

Parameters:

spaceKey - identifies the space to which the results are restricted.

Returns:

a list of label instances in order of most recently used to least recently used.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getRecentlyUsedLabelsInSpace

public List getRecentlyUsedLabelsInSpace(String spaceKey,
                                         int maxResults)

Retrieve the most recently used labels within the specified spae.

Parameters:

spaceKey -

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label instances in order of the most recently used to least recently used.

getRecentlyUsedLabellingsInSpace

public List getRecentlyUsedLabellingsInSpace(String spaceKey,
                                             int maxResults)

getSuggestedLabels

public List getSuggestedLabels(ContentEntityObject content)

Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content. The process used to identify 'suggested' labels may change and therefore is not defined here.

Parameters:

content -

Returns:

a list of label instances. The order of these labels is undefined.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getSuggestedLabels

public List getSuggestedLabels(ContentEntityObject content,
                               int maxResults)

Retrieve the suggested labels for the specified content. The process used to identify 'suggested' labels may change and therefore is not defined here.

Parameters:

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label instances. The order of these labels is undefined.

getSuggestedLabelsInSpace

public List getSuggestedLabelsInSpace(ContentEntityObject content,
                                      String spaceKey)

Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content bound to the specified space.

Parameters:

content -

spaceKey -

Returns:

a list of label instances. The order of these labels is undefined.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getSuggestedLabelsInSpace

public List getSuggestedLabelsInSpace(ContentEntityObject content,
                                      String spaceKey,
                                      int maxResults)

Retrieve the suggested labels for the specified content bound to the specified space.

Parameters:

content -

spaceKey -

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label instances. The order of these labels is undefined.

getRelatedLabels

public List getRelatedLabels(Label label)

Retrieve the DEFAULT_LABEL_COUNT labels that are 'related' to the specified label. The process used to identify 'related' labels may change and therefore is not define here.

Parameters:

label -

Returns:

a list of label instances. The order of these labels is undefined.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getRelatedLabels

public List getRelatedLabels(Label label,
                             int maxResults)

Retrieve the labels that are 'related' to the specified label. The process used to identify 'related' labels may change and therefore is not defined here.

Parameters:

maxResults - is the maximum number of labels to be returned.

Returns:

a list of label instances. The order of these labels is undefined.

getRelatedLabelsInSpace

public List getRelatedLabelsInSpace(Label label,
                                    String spaceKey)

Retrieve the DEFAULT_LABEL_COUNT labels that are 'related' to the specified label and that are used to label content within the specified space.

Parameters:

label -

spaceKey -

Returns:

a list of label instances. The order of these labels is undefined.

See Also:

LabelManager.DEFAULT_LABEL_COUNT

getRelatedLabelsInSpace

public List getRelatedLabelsInSpace(Label label,
                                    String spaceKey,
                                    int maxResults)

Retrieve the labels that are 'related' to the specified label and that are used to to label content within the specified space.

Parameters:

label -

spaceKey -

maxResults -

Returns:

a list of label instance. The order of these labels is undefined.

getSpacesContainingContentWithLabel

public List getSpacesContainingContentWithLabel(Label label)

Look up the spaces that have been labelled by the specific label.

Parameters:

label -

Returns:

a list of Spaces. The order of these labels is undefined.

getUsersLabels

public List getUsersLabels(String owner)

Retrieve the personal labels that belong to the specified user.

Parameters:

owner -

getTeamLabels

public List getTeamLabels()

Retrieve all of the team labels in the system.

Returns:

a list of labels with the namespace Namespace.TEAM

getTeamLabelsForSpace

public List getTeamLabelsForSpace(String spaceKey)

Retrieve all of the team labels used to label content in the specified space.

Parameters:

spaceKey -

Returns:

a list of team labels with the namespace Namespace.TEAM. The order of the list is undefined.

getCurrentContentForLabel

public List getCurrentContentForLabel(Label label)

Get all content associated with a label and space Get all current content associated with a label and any space. Content in the trash will not be returned.

Returns:

a list of ContentEntityObjects

getCurrentContentForLabelAndSpace

public List getCurrentContentForLabelAndSpace(Label label,
                                              String spaceKey)

Get all current content associated with a label and space. Content in the trash will not be returned.

Returns:

a list of ContentEntityObjects

getCurrentContentWithPersonalLabel

public List getCurrentContentWithPersonalLabel(String username)

Get all current content labelled by a user

getSpacesWithLabel

public List getSpacesWithLabel(Label label)

Spaces cannot be directly labelled. Howevever, their space descriptions can. This method searches for all space descriptions with the label passed in

Parameters:

label -

Returns:

list of spaces associated with matching space descriptions

getFavouriteSpaces

public List getFavouriteSpaces(String username)

Parameters:

username - username of label owner

getRecentlyUsedPersonalLabels

public List getRecentlyUsedPersonalLabels(String username)

Retrieve the labels that were recently used by currently authenticated user. 'Recently Used' includes labels that the user recently added, created, removed and deleted.

Note: labels in this list may or may not exist.

The UserHistory can be retrieved from the session via the ActionContext (if using an action) or the Execution Context (DWR)

Parameters:

username - the user history from the session

Returns:

a list of labels

getRecentlyUsedPersonalLabels

public List getRecentlyUsedPersonalLabels(String username,
                                          int maxResults)

Retrieve the labels that were recently used by currently authenticated user. 'Recently Used' includes labels that the user recently added, created, removed and deleted.

Note: labels in this list may or may not exist.

The UserHistory can be retrieved from the session via the ActionContext (if using an action) or the Execution Context (DWR)

Parameters:

maxResults - the maximum number of results to return to the user

username - the user history from the session

Returns:

a list of labels

getRecentlyUsedPersonalLabellings

public List getRecentlyUsedPersonalLabellings(String username,
                                              int maxResults)

getContent

public List getContent(Label label)

getContentCount

public int getContentCount(Label label)

createLabel

public Label createLabel(Label label)