Package com.atlassian.confluence.api.service.relations

Interface RelationService

All Known Implementing Classes:
RelationServiceImpl
public interface RelationService
Relation service, which allows to manage relations between entities. "Relations" are used when it's needed to mark related content. Good examples of relations are Watches (when user marks certain pages as watchable), Likes (user marks content as "Liked") or Favourites (content is marked as favourite by user) (all are "user2content" type of relations).

For example, to create a favourite relation between a user and the DEV Space : 

     relationService.create(RelationInstance.builder(user, new SpaceFavouriteRelation(), space).build));
 assertTrue(relationService.isRelated(user, new SpaceFavouriteRelation(), space));
and to find the favourite spaces of a user : 
     relationService.findTargets(user, new SpaceFavouriteRelation()).fetchMany(new SimplePageRequest(0, 10));

IMPORTANT: there is no security validation for user, there is only security validation for content. It's 100% responsibility of the consumer to check current user permissions for deletion of user relations!

Since:
5.9
See Also:

  • Method Details

    • create

      <S extends Relatable, T extends Relatable> RelationInstance<S,T> create(RelationInstance<S,T> relationInstance) throws ServiceException
      Creates a directed relation between two relatable entities.

      For example, when a user favourites a space a SpaceFavouriteRelation is created from the user to the space: 

           relationService.create(RelationInstance.builder(user, new SpaceFavouriteRelation(), space).build));
      Type Parameters:
      S - type of the source entity
      T - type of the target entity
      Parameters:
      relationInstance - the relation to create
      Returns:
      the newly created relationInstance
      Throws:
      ServiceException - if validation fails

    • delete

      <S extends Relatable, T extends Relatable> void delete(RelationInstance<S,T> relationInstance) throws ServiceException
      Remove a relation if it exists between a source and a target relatable entity
      Type Parameters:
      S - type of the source entity
      T - type of the target entity
      Parameters:
      relationInstance - relation to be deleted
      Throws:
      ServiceException - if validation fails

    • isRelated

      <S extends Relatable, T extends Relatable> boolean isRelated(S source, RelationDescriptor<S,T> relationDescriptor, T target)
      Determine whether a given source and target are related by the given relation
      Type Parameters:
      S - type of the source entity
      T - type of the target entity
      Returns:
      true if the relation exists between the given source and target

    • validator

      RelationService.Validator validator()
      Returns:
      a new validator to validate create and delete operations that can be performed using the RelationService

    • findTargets

      <S extends Relatable, T extends Relatable> RelationService.RelatableFinder<T> findTargets(S source, RelationDescriptor<S,T> relationDescriptor)
      Create a finder to find targets of a relation. This method is used to find all targets for given relation and given source. For example, it can be used in operations like "findAllFavouriteContentForGivenUser" (user2content relation) or "findAllUsersThisUserIsFollowingTo" (user2user relation)

      For example, to find spaces that a user has favourites : 

           relationService.findTargets(user, new SpaceFavouriteRelation()).fetchMany(new SimplePageRequest(0,
 10));
      Type Parameters:
      S - the type of the source entity
      T - the type of the target entity
      Parameters:
      source - the source entity (LHS) of the relation
      relationDescriptor - the type of relation to find
      Returns:
      a finder to find targets of a relation.

    • findSources

      <S extends Relatable, T extends Relatable> RelationService.RelatableFinder<S> findSources(T target, RelationDescriptor<S,T> relationDescriptor)
      Create a finder to find sources of a relation.

      This method is used to find all sources for given relation and given source. For example, it can be used in operations like "findAllUsersWhoFavouritedThisPage" (user2content relation) or "findAllFollowers" (user2user relation)

      For example, to find users that favourite a particular space : 

           relationService.findSources(space, new SpaceFavouriteRelation()).fetchMany(new SimplePageRequest(0,
 10));
      Type Parameters:
      S - the type of the source entity
      T - the type of the target entity
      Parameters:
      target - the target entity (RHS) of the relation
      relationDescriptor - the type of relation to find
      Returns:
      a finder to find targets of a relation.

    • removeAllRelationsFromEntityWithType

      <S extends Relatable, T extends Relatable> void removeAllRelationsFromEntityWithType(RelationDescriptor<S,T> relationDescriptor, Relatable relatable)
      Remove all relations of the given type where the given entity participates
      Type Parameters:
      S - the type of the source entity in the relation type
      T - the type of the target entity in the relation type
      Parameters:
      relationDescriptor - relation descriptor representing the type of relation to remove
      relatable - the entity participating in the relationships