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:
    RelationInstance, Relatable, RelationDescriptor
    • Method Detail

      • create

        <S extends Relatable,​T extends RelatableRelationInstance<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 RelatableRelationService.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 RelatableRelationService.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