Package 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:

  • Method Summary

    Modifier and Type
    Method
    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 Details

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