com.atlassian.confluence.api.service.relations

Interface RelationService

All Known Implementing Classes:

RelationServiceImpl

@ExperimentalApi
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

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	RelationService.RelatableFinder<R extends Relatable> Finder, which is used to perform basic relation operations, such as fetching source or target entities of particular relation, get total number of related entities etc.
static interface	RelationService.Validator Responsible for validating the create and delete operations that can be performed using the RelationService

Method Summary

Modifier and Type	Method and Description
<S extends Relatable,T extends Relatable> RelationInstance<S,T>	create(RelationInstance<S,T> relationInstance) Creates a directed relation between two relatable entities.
<S extends Relatable,T extends Relatable> void	delete(RelationInstance<S,T> relationInstance) Remove a relation if it exists between a source and a target relatable entity
<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.
<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.
<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
<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
RelationService.Validator	validator()

Method Detail

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