com.almworks.jira.structure.api.structure.favorite

Interface StructureFavoriteManager

@PublicApi
public interface StructureFavoriteManager

StructureFavoriteManager manages "favorite" relations between users and structures.

Any user can mark a structure as their favorite, so they can quickly access it later. Hence, a user has a set of favorite structures, and a structure has popularity - the number of users who have marked it as their favorite.

If a structure which is marked as favorite by a user becomes inaccessible for that user, it still remains their favorite. If the user does not have the VIEW access to a structure, they shouldn't be able to see it, whether it's their favorite or not.

Except for getFavorites(com.atlassian.jira.user.ApplicationUser), none of the methods of this class perform any permission checks, so the calling code should check if the user has PermissionLevel.VIEW permission on their favorite structures.

Anonymous user does not have any favorites.

Since:

7.2.0 (Structure 2.0)

See Also:

StructureManager

Method Summary

Modifier and Type	Method and Description
List<Structure>	filterByPopularity(List<Structure> structures, int minPopularity, int maxPopularity) Filters a list of structures, producing another list with structures that match popularity criteria, defined by minimum and maximum popularity.
Map<String,LongArray>	getAllFavorites()
List<Structure>	getFavorites(ApplicationUser user) Returns a list of unarchived structures that are the user's favorite and that the user is allowed to see.
List<Structure>	getFavorites(ApplicationUser user, boolean includeArchivedStructures) Returns a list of structures that are the user's favorite and that the user is allowed to see.
int	getPopularity(Long structureId) Returns the number of users for whom the structure is favorite.
boolean	isFavorite(Long structureId, ApplicationUser user) Tells whether the structure is among user's favorite structures.
void	setFavorite(Long structureId, ApplicationUser user, boolean favorite) Adds or removes the structure from user's favorites.
void	sortByPopularity(List<Structure> structures, ApplicationUser user) Sorts a list of structures by their popularity (descending).

Method Detail

isFavorite

boolean isFavorite(@Nullable
                   Long structureId,
                   @Nullable
                   ApplicationUser user)

Tells whether the structure is among user's favorite structures. This method does not check if the user has PermissionLevel.VIEW on the structure and would return true for a favorite structure even if the user no longer has the right to view it.

Parameters:

structureId - the ID of the structure.

user - the user.

Returns:

true if the structure is favorite, false if otherwise or if any input parameter is null.

setFavorite

void setFavorite(@Nullable
                 Long structureId,
                 @Nullable
                 ApplicationUser user,
                 boolean favorite)

Adds or removes the structure from user's favorites. This method does not check if the user has PermissionLevel.VIEW on the structure and would perform even if the user doesn't have the right to view the structure.

Calling this method on the null user or structure has no effect.

Parameters:

structureId - the ID of the structure.

user - the user on whose favorites the operation should be performed.

favorite - true if the structure should be made user's favorite, false if it should be made not user's favorite.

getPopularity

int getPopularity(@Nullable
                  Long structureId)

Returns the number of users for whom the structure is favorite. If the result is shown to a user, the calling code should ensure that the user has PermissionLevel.VIEW on the structure.

Parameters:

structureId - the ID of the structure.

Returns:

the number of users for whom the structure is favorite. Returns 0 if structureId is null.

getFavorites

@NotNull
List<Structure> getFavorites(@Nullable
                                      ApplicationUser user)

Returns a list of unarchived structures that are the user's favorite and that the user is allowed to see.

The resulting list is sorted by structure name.

Parameters:

user - the user whose favorites should be returned.

Returns:

a list of the user's favorite unarchived structures. If user is null, an empty list is returned.

getFavorites

@NotNull
List<Structure> getFavorites(@Nullable
                                      ApplicationUser user,
                                      boolean includeArchivedStructures)

Returns a list of structures that are the user's favorite and that the user is allowed to see.

The resulting list is sorted by structure name.

Parameters:

user - the user whose favorites should be returned.

includeArchivedStructures - if true, result will also contain archived structures

Returns:

a list of the user's favorite structures. If user is null, an empty list is returned.

getAllFavorites

@NotNull
Map<String,LongArray> getAllFavorites()

sortByPopularity

void sortByPopularity(@Nullable
                      List<Structure> structures,
                      @Nullable
                      ApplicationUser user)

Sorts a list of structures by their popularity (descending). If the list is going to be shown to a user, the calling code should ensure that the user has PermissionLevel.VIEW on every structure in the list.

If two structures have the same popularity, they are sorted based on their name.

Parameters:

structures - a modifiable list of structures for sorting.

user - a user to whom the list will be shown. It is needed to properly sort structures with equal popularity (to use proper locale for name comparison). If null, the default system locale is used. No permission checks are made for this user.

filterByPopularity

@NotNull
List<Structure> filterByPopularity(@Nullable
                                            List<Structure> structures,
                                            int minPopularity,
                                            int maxPopularity)

Filters a list of structures, producing another list with structures that match popularity criteria, defined by minimum and maximum popularity.

If the list is going to be shown to a user, the calling code should ensure that the user has PermissionLevel.VIEW on every structure in the list.

This method always returns writable list, even if the result is empty.

Parameters:

structures - a list of structures for filtering, may be non-modifiable

minPopularity - minimum popularity (inclusive). If you don't need to filter by minimum popularity, use 0.

maxPopularity - maximum popularity (inclusive). If you don't need to filter by maximum popularity, use Integer.MAX_VALUE.

Returns:

a new list with those structures that pass popularity filter, in the same order. The list is writable and can be owned by the calling code, even if it is empty.