public interface

LabelManager

com.atlassian.confluence.labels.LabelManager
Known Indirect Subclasses

Class Overview

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

Summary

Constants
int DEFAULT_LABEL_COUNT
String FAVOURITE_LABEL
String FAVOURITE_LABEL_YANKEE
int LABEL_ADDED Indicates that a label was added.
int LABEL_CREATED Indicates that a label was created.
int LABEL_DELETED Indicates that a label was deleted.
int LABEL_REMOVED Indicates that a label was removed.
int NO_CHANGE Indicates no change.
Fields
public static final List CONTENT_TYPES Content Types that can have a label applied.
Public Methods
abstract int addLabel(ContentEntityObject content, Label label)
Add a label to the specified content.
abstract Label createLabel(Label label)
abstract boolean deleteLabel(Label l)
Delete the specified label.
abstract boolean deleteLabel(long id)
Delete the label with the specified id.
abstract List getContent(Label label)
abstract int getContentCount(Label label)
abstract List<ContentEntityObject> getContentForAllLabels(Collection<Label> labels, int maxResults, int offset)
Retrieve all ContentEntityObjects which are labelled with ALL provided labels.
abstract List<ContentEntityObject> getContentForLabel(Label label, int maxResults)
Get all content associated with a label Get all versions of content associated with a label and any space.
abstract List getCurrentContentForLabel(Label label)
Get all content associated with a label and space Get all current content associated with a label and any space.
abstract List getCurrentContentForLabelAndSpace(Label label, String spaceKey)
Get all current content associated with a label and space.
abstract List getCurrentContentWithPersonalLabel(String username)
Get all current content labelled by a user
abstract List<Space> getFavouriteSpaces(String username)
abstract Label getLabel(long id)
Retrieve the label with the specified id.
abstract Label getLabel(ParsedLabelName parsedLabelName)
Retrieve the label by name.
abstract Label getLabel(String unparsedLabelName)
convenience method to fetch a label without having to call the label parser
abstract Label getLabel(Label label)
Retrieve the persistent instance of the label with the exact same details as the specified label.
abstract List getLabels(Collection unparsedLabelNames)
convenience method to fetch labels without having to call the label parser
abstract List getLabelsByDetail(String labelName, String namespace, String spaceKey, String owner)
Retrieves the labels matching the given labelName, namespace or owner
abstract List getLabelsInSpace(String key)
Retrieve all of the labels that label content within the specified space.
abstract List getMostPopularLabels(int maxResults)
Retrieve the most popular labels within the system.
abstract List getMostPopularLabels()
Retrieve the list of the DEFAULT_LABEL_COUNT most popular labels within the system.
abstract 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.
abstract 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.
abstract 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.
abstract Set getMostPopularLabelsWithRanks(int maxResults, Comparator comparator)
Retrieve the most popular labels within the system, including their ranks and ordered using the comparator provided.
abstract 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.
abstract List getRecentlyUsedLabellings(int maxResults)
abstract List getRecentlyUsedLabellingsInSpace(String spaceKey, int maxResults)
abstract List getRecentlyUsedLabels(int maxResults)
Retrieve the x most recently used labels.
abstract List getRecentlyUsedLabels()
Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the system.
abstract List getRecentlyUsedLabelsInSpace(String spaceKey)
Retrieve the DEFAULT_LABEL_COUNT most recently used labels within the specified space.
abstract List getRecentlyUsedLabelsInSpace(String spaceKey, int maxResults)
Retrieve the most recently used labels within the specified spae.
abstract List getRecentlyUsedPersonalLabellings(String username, int maxResults)
abstract List getRecentlyUsedPersonalLabels(String username)
Retrieve the labels that were recently used by currently authenticated user.
abstract List getRecentlyUsedPersonalLabels(String username, int maxResults)
Retrieve the labels that were recently used by currently authenticated user.
abstract List getRelatedLabels(Label label, int maxResults)
Retrieve the labels that are 'related' to the specified label.
abstract List getRelatedLabels(Label label)
Retrieve the DEFAULT_LABEL_COUNT labels that are 'related' to the specified label.
abstract List getRelatedLabels(List labels, String spaceKey, int maxResultsPerLabel)
Retrieve the labels that are 'related' to the labels in the list.
abstract 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.
abstract 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.
abstract List getSpacesContainingContentWithLabel(Label label)
Look up the spaces that have been labelled by the specific label.
abstract List<Space> getSpacesWithLabel(Label label)
Spaces cannot be directly labelled.
abstract List getSuggestedLabels(ContentEntityObject content, int maxResults)
Retrieve the suggested labels for the specified content.
abstract List getSuggestedLabels(ContentEntityObject content)
Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content.
abstract List getSuggestedLabelsInSpace(ContentEntityObject content, String spaceKey, int maxResults)
Retrieve the suggested labels for the specified content bound to the specified space.
abstract List getSuggestedLabelsInSpace(ContentEntityObject content, String spaceKey)
Retrieve the DEFAULT_LABEL_COUNT suggested labels for the specified content bound to the specified space.
abstract List getTeamLabels()
Retrieve all of the team labels in the system.
abstract List getTeamLabelsForSpace(String spaceKey)
Retrieve all of the team labels used to label content in the specified space.
abstract List<Label> getTeamLabelsForSpaces(Collection<Space> spaces)
Retrieve all of the team labels used to label content in the specified spaces.
abstract List getUsersLabels(String owner)
Retrieve the personal labels that belong to the specified user.
abstract void removeAllLabels(ContentEntityObject content)
Remove all of the labels from the specified content.
abstract int removeLabel(ContentEntityObject object, Label label)
Remove a label from the specified content.
abstract void removeLabels(ContentEntityObject object, List labels)

Constants

public static final int DEFAULT_LABEL_COUNT

Constant Value: 100 (0x00000064)

public static final String FAVOURITE_LABEL

Constant Value: "favourite"

public static final String FAVOURITE_LABEL_YANKEE

Constant Value: "favorite"

public static final int LABEL_ADDED

Indicates that a label was added.

See Also
Constant Value: 1 (0x00000001)

public static final int LABEL_CREATED

Indicates that a label was created.

See Also
Constant Value: 2 (0x00000002)

public static final int LABEL_DELETED

Indicates that a label was deleted.

See Also
Constant Value: 4 (0x00000004)

public static final int LABEL_REMOVED

Indicates that a label was removed.

See Also
Constant Value: 3 (0x00000003)

public static final int NO_CHANGE

Indicates no change.

See Also
Constant Value: 0 (0x00000000)

Fields

public static final List CONTENT_TYPES

Content Types that can have a label applied.

Public Methods

public abstract 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"));
Returns
  • one of NO_CHANGE, LABEL_ADDED or LABEL_CREATED

public abstract Label createLabel (Label label)

public abstract 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.
Returns
  • true if the label was deleted, false otherwise.

public abstract boolean deleteLabel (long id)

Delete the label with the specified id.

Returns
  • true if the label was deleted, false otherwise.

public abstract List getContent (Label label)

public abstract int getContentCount (Label label)

public abstract List<ContentEntityObject> getContentForAllLabels (Collection<Label> labels, int maxResults, int offset)

Retrieve all ContentEntityObjects which are labelled with ALL provided labels.

Parameters
labels labels which must appear on ContentEntityObjects
maxResults the maximum number of results to return
offset the offset into the results
Returns
  • a list of ContentEntityObjects labelled with the labels provided

public abstract List<ContentEntityObject> getContentForLabel (Label label, int maxResults)

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

Returns
  • a list of ContentEntityObjects

public abstract 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

public abstract 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

public abstract List getCurrentContentWithPersonalLabel (String username)

Get all current content labelled by a user

public abstract List<Space> getFavouriteSpaces (String username)

Parameters
username username of label owner

public abstract Label getLabel (long id)

Retrieve the label with the specified id.

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

public abstract Label getLabel (ParsedLabelName parsedLabelName)

Retrieve the label by name.

Returns
  • a persistent instance of the label or null if it can not be found.
See Also

public abstract Label getLabel (String unparsedLabelName)

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

Parameters
unparsedLabelName - example - my:foo

public abstract 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.

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

public abstract List getLabels (Collection unparsedLabelNames)

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

Parameters
unparsedLabelNames - example - my:foo, bar

public abstract 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

public abstract 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.

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract 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

public abstract List getRecentlyUsedLabellings (int maxResults)

public abstract List getRecentlyUsedLabellingsInSpace (String spaceKey, int maxResults)

public abstract 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.

public abstract 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

public abstract 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

public abstract List getRecentlyUsedLabelsInSpace (String spaceKey, int maxResults)

Retrieve the most recently used labels within the specified spae.

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

public abstract List getRecentlyUsedPersonalLabellings (String username, int maxResults)

public abstract 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

public abstract 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
username the user history from the session
maxResults the maximum number of results to return to the user
Returns
  • a list of labels

public abstract 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.

public abstract 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.

Returns
  • a list of label instances. The order of these labels is undefined.
See Also

public abstract List getRelatedLabels (List labels, String spaceKey, int maxResultsPerLabel)

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

Parameters
spaceKey - may be null to search globally
maxResultsPerLabel is the maximum number of labels to be returned for each label.
Returns
  • a list of label instances. The order of these labels is undefined.

public abstract 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.

Returns
  • a list of label instances. The order of these labels is undefined.
See Also

public abstract 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.

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

public abstract List getSpacesContainingContentWithLabel (Label label)

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

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

public abstract List<Space> 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

Returns
  • list of spaces associated with matching space descriptions

public abstract 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.

public abstract 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.

Returns
  • a list of label instances. The order of these labels is undefined.
See Also

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

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

Parameters
maxResults is the maximum number of labels to be returned.
Returns
  • a list of label instances. The order of these labels is undefined.

public abstract List getSuggestedLabelsInSpace (ContentEntityObject content, String spaceKey)

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

Returns
  • a list of label instances. The order of these labels is undefined.
See Also

public abstract List getTeamLabels ()

Retrieve all of the team labels in the system.

Returns
  • a list of labels with the namespace Namespace.TEAM

public abstract List getTeamLabelsForSpace (String spaceKey)

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

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

public abstract List<Label> getTeamLabelsForSpaces (Collection<Space> spaces)

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

Parameters
spaces collection of spaces whose labels to get
Returns
  • a list of team labels with the namespace Namespace.TEAM. The order of the list is undefined.

public abstract List getUsersLabels (String owner)

Retrieve the personal labels that belong to the specified user.

public abstract void removeAllLabels (ContentEntityObject content)

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

public abstract int removeLabel (ContentEntityObject object, Label label)

Remove a label from the specified content.

Returns
  • one of NO_CHANGE, LABEL_DELETED, LABEL_REMOVED

public abstract void removeLabels (ContentEntityObject object, List labels)