com.jivesoftware.community.user.relationships
Interface UserRelationshipManager

public interface UserRelationshipManager

Method Summary

void	approveRelationship(UserRelationship userRelationship, String responseMessage)
boolean	canViewRelationshipLists(User user)
UserRelationship	createRelationship(long userID, long relatedUserID, int relationshipType, long relationshipGraphID, String requestMessage) Create a relationship between two users.
UserRelationship	createRelationship(User user, User relatedUser, UserRelationshipGraph relationshipGraph, String requestMessage) Create a relationship between two users.
UserRelationshipGraph	createRelationshipGraph(String name, UserRelationshipGraph.GraphType graphType) Create a new relationship graph with a given name and persist it.
UserRelationshipList	createRelationshipList(String name, String label, User owner) Create a new UserRelationshipList.
void	deleteRelationshipGraph(long relationshipGraphID) Remove the graph from the peristence layer.
void	deleteRelationshipList(UserRelationshipList list) Delete a list and all child relationships from the DB.
void	deleteUserRelationships(User user) Delete all relationships related to the given user, regardless of which end of the relationship the given user exists.
Iterable<UserRelationshipView>	getAllActiveRelationships(UserRelationshipManagerImpl.UserRelationshipResultFilter filter) Get a list of active user relationships for a given graph (for admin console purposes).
UserRelationshipView	getApprovalViewForUserRelationship(UserRelationship rel, long requestingUserID) Create a specific view for a relationship depending on who is requesting the view.
Set<Long>	getApproverUserIDs(User requester, UserRelationship userRelationship)
List<User>	getColleagues(User user, HierarchicalUserRelationshipGraph graph) Get a list of a user's colleagues (people who report to the same manager, minus the user) (may return empty list, but not null).
Map<UserRelationshipGraph,Collection<UserRelationshipView>>	getCurrentRelationshipMap(User user, boolean approvedOnly) Get a map of relationship views revolving around the user argument.
Collection<UserRelationshipView>	getCurrentRelationships(User user, UserRelationshipGraph graph, boolean approvedOnly) Get a collection of relationship views revolving around the user argument.
HierarchicalUserRelationshipGraph	getDefaultHierarchicalRelationshipGraph() Find the default (primary) HierarchicalUserRelationshipGraph.
MeshUserRelationshipGraph	getDefaultMeshRelationshipGraph() Find the default (primary) MeshUserRelationshipGraph.
List<User>	getDirectReports(User manager, HierarchicalUserRelationshipGraph graph) Get a list of a user's direct reports (may return empty list, but not null).
List<User>	getEscalationChain(User user, HierarchicalUserRelationshipGraph graph) Build a list of people upward in the hierarchical org from a given user.
UserRelationship	getFriendRelationship(User user1, User user2, MeshUserRelationshipGraph graph) If two users have a relationship in a given graph, return it, else return null.
List<UserRelationshipView>	getFriends(User user) Get an list of a user's friends from the default mesh graph.
List<UserRelationshipView>	getFriends(User user, MeshUserRelationshipGraph graph) Get an list of a user's friends in a given mesh graph.
List<UserRelationshipView>	getInverseFriends(User user, MeshUserRelationshipGraph graph) Get a list of who has friended a user, for a non-reflexive graph.
User	getManager(User user, HierarchicalUserRelationshipGraph graph) Get a user's current manager in a hierarchical graph, or null if no manager is found.
UserRelationship	getManagerRelationship(User user, HierarchicalUserRelationshipGraph graph) Get a user's current manager.
Set<Long>	getNotificationUserIDs(User requester, UserRelationship userRelationship)
Collection<UserRelationshipView>	getPendingRelationships(User user, UserRelationshipGraph graph) Get a list of not-yet-approved relationships for a given graph.
Map<UserRelationshipGraph,Collection<UserRelationshipView>>	getPossibleRelationshipMap(User user, User relatedUser)
Collection<UserRelationshipView>	getPossibleRelationships(User user, User relatedUser, UserRelationshipGraph graph) Get a collection of relationship views (per graph) showing the possible relationships between two users.
UserRelationship	getRelationship(long relationshipID) Get a given relationship for its ID.
UserRelationshipGraph	getRelationshipGraph(long relationshipGraphID) Get a graph for a given graph ID.
Collection<UserRelationshipGraph>	getRelationshipGraphs(boolean enabledOnly) Get a collection of all graphs in the system, regardless of state (enabled or disabled).
UserRelationshipList	getRelationshipList(long listID) Retrive a relationship list by ID.
Collection<UserRelationshipList>	getRelationshipListsByOwner(User owner) Retrieves a collection of lists based on an owner userID.
Collection<UserRelationshipList>	getRelationshipListsByPerson(User person, User owner) Retrieves a collection of lists based on an owner userID and a person who is on the list.
List<UserRelationshipView>	getRelationshipListUsers(UserRelationshipList list) Get a list of users from a user relationship list.
int	getUserRelationshipCount() Get a count of all UserRelationships.
int	getUserRelationshipCount(UserRelationshipManagerImpl.UserRelationshipResultFilter filter) Get a filtered count of all UserRelationships.
boolean	isFriend(User user1, User user2, MeshUserRelationshipGraph graph) In a reflexive mesh graph, are user1 and user2 friends?
boolean	isFriendingEnabled() Is the friending feature enabled?
boolean	isOrgChartingEnabled() Is the organizational relationship feature enabled?
void	notifyUsers(String key, User requester, UserRelationship relationship, Map<String,Object> additonalContext) Send a notification corresponding to an event (creation, approval, rejection, retirement) of a UserRelationship.
void	rejectRelationship(UserRelationship userRelationship, String responseMessage)
void	retireRelationship(User retirer, UserRelationship userRelationship) Set relationship to be retired and persist the change in the DB.
void	retireRelationships(User user) Retire all current relationships for a given user (for example, on disabling an account).
void	updateRelationship(UserRelationship userRelationship)
void	updateRelationshipGraph(UserRelationshipGraph relationshipGraph) Persist any changes to the graph.
void	updateRelationshipList(UserRelationshipList list) Update the name or labelStyle of a list.

Method Detail

isOrgChartingEnabled

boolean isOrgChartingEnabled()

Is the organizational relationship feature enabled?

Returns:

the enabled state of the feature.

isFriendingEnabled

boolean isFriendingEnabled()

Is the friending feature enabled?

Returns:

the enabled state of the feature.

createRelationshipGraph

UserRelationshipGraph createRelationshipGraph(String name,
                                              UserRelationshipGraph.GraphType graphType)

Create a new relationship graph with a given name and persist it.

Parameters:

name - The name (title) of this graph.

graphType - The GraphType (Hierarchical or Mesh) of the graph that is being created.

Returns:

a newly created and persisted object that implements UserRelationshipGraph.

getRelationshipGraph

UserRelationshipGraph getRelationshipGraph(long relationshipGraphID)

Get a graph for a given graph ID.

Parameters:

relationshipGraphID - The ID of the graph to return.

Returns:

an object that implements UserRelationshipGraph.

updateRelationshipGraph

void updateRelationshipGraph(UserRelationshipGraph relationshipGraph)

Persist any changes to the graph. Note that graph type cannot be updated once created.

Parameters:

relationshipGraph - an object that implements UserRelationshipGraph.

deleteRelationshipGraph

void deleteRelationshipGraph(long relationshipGraphID)

Remove the graph from the peristence layer.

WARNING: this will remove all relationships associated with this graph as well.

Parameters:

relationshipGraphID - The ID of the graph to delete.

getDefaultHierarchicalRelationshipGraph

HierarchicalUserRelationshipGraph getDefaultHierarchicalRelationshipGraph()

Find the default (primary) HierarchicalUserRelationshipGraph. If no default graph is found, null is returned.

Returns:

getDefaultMeshRelationshipGraph

MeshUserRelationshipGraph getDefaultMeshRelationshipGraph()

Find the default (primary) MeshUserRelationshipGraph. If no default graph is found, null is returned.

Returns:

getRelationshipGraphs

Collection<UserRelationshipGraph> getRelationshipGraphs(boolean enabledOnly)

Get a collection of all graphs in the system, regardless of state (enabled or disabled).

Parameters:

enabledOnly -

Returns:

a Collection of UserRelationshipGraphs.

createRelationship

UserRelationship createRelationship(long userID,
                                    long relatedUserID,
                                    int relationshipType,
                                    long relationshipGraphID,
                                    String requestMessage)
                                    throws UserRelationshipException

Create a relationship between two users. If the graph is hierarchical, user will be relatedUser's manager. Otherwise, user will be relatedUser's peer.

Parameters:

userID -

relatedUserID -

relationshipType -

relationshipGraphID -

requestMessage -

Returns:

Throws:

UserRelationshipAlreadyExistsException

UserRelationshipException

createRelationship

UserRelationship createRelationship(User user,
                                    User relatedUser,
                                    UserRelationshipGraph relationshipGraph,
                                    String requestMessage)
                                    throws UserRelationshipException

Create a relationship between two users. If the graph is hierarchical, user will be relatedUser's manager. Otherwise, user will be relatedUser's peer.

Parameters:

user -

relatedUser -

relationshipGraph -

Returns:

Throws:

UserRelationshipAlreadyExistsException - If this relationship already exists (in either direction for peer relationships, or if relatedUser already has a manager for hierarchical relationships).

UserRelationshipException

deleteUserRelationships

void deleteUserRelationships(User user)
                             throws UnauthorizedException

Delete all relationships related to the given user, regardless of which end of the relationship the given user exists.

Parameters:

user - The user or relatedUser within the relationships being deleted.

Throws:

UnauthorizedException - If the currently authenticated user is not a sys-admin or user-admin.

getCurrentRelationshipMap

Map<UserRelationshipGraph,Collection<UserRelationshipView>> getCurrentRelationshipMap(User user,
                                                                                      boolean approvedOnly)

Get a map of relationship views revolving around the user argument. The map is keyed by the graphs of the relationships and shows one level of removal from the user for any graph.

Parameters:

user -

approvedOnly -

Returns:

getCurrentRelationships

Collection<UserRelationshipView> getCurrentRelationships(User user,
                                                         UserRelationshipGraph graph,
                                                         boolean approvedOnly)

Get a collection of relationship views revolving around the user argument.

Parameters:

user -

graph -

approvedOnly -

Returns:

getPossibleRelationshipMap

Map<UserRelationshipGraph,Collection<UserRelationshipView>> getPossibleRelationshipMap(User user,
                                                                                       User relatedUser)

getPossibleRelationships

Collection<UserRelationshipView> getPossibleRelationships(User user,
                                                          User relatedUser,
                                                          UserRelationshipGraph graph)

Get a collection of relationship views (per graph) showing the possible relationships between two users. Possible relationships are relationships that don't exist yet or aren't pending approval.

Parameters:

user -

graph -

Returns:

getPendingRelationships

Collection<UserRelationshipView> getPendingRelationships(User user,
                                                         UserRelationshipGraph graph)

Get a list of not-yet-approved relationships for a given graph.

Parameters:

user -

graph -

Returns:

getRelationship

UserRelationship getRelationship(long relationshipID)

Get a given relationship for its ID.

Parameters:

relationshipID -

Returns:

getManagerRelationship

UserRelationship getManagerRelationship(User user,
                                        HierarchicalUserRelationshipGraph graph)

Get a user's current manager. NOTE: the relationship may or may not be approved.

Returns:

retireRelationships

void retireRelationships(User user)

Retire all current relationships for a given user (for example, on disabling an account).

Parameters:

the - user to disable all relationships for.

retireRelationship

void retireRelationship(User retirer,
                        UserRelationship userRelationship)

Set relationship to be retired and persist the change in the DB.

Parameters:

userRelationship -

updateRelationship

void updateRelationship(UserRelationship userRelationship)

approveRelationship

void approveRelationship(UserRelationship userRelationship,
                         String responseMessage)

rejectRelationship

void rejectRelationship(UserRelationship userRelationship,
                        String responseMessage)

getApproverUserIDs

Set<Long> getApproverUserIDs(User requester,
                             UserRelationship userRelationship)

getNotificationUserIDs

Set<Long> getNotificationUserIDs(User requester,
                                 UserRelationship userRelationship)

getApprovalViewForUserRelationship

UserRelationshipView getApprovalViewForUserRelationship(UserRelationship rel,
                                                        long requestingUserID)

Create a specific view for a relationship depending on who is requesting the view.

Parameters:

rel -

requestingUserID -

Returns:

notifyUsers

void notifyUsers(String key,
                 User requester,
                 UserRelationship relationship,
                 Map<String,Object> additonalContext)

Send a notification corresponding to an event (creation, approval, rejection, retirement) of a UserRelationship.

Parameters:

key -

requester -

relationship -

additonalContext -

getEscalationChain

List<User> getEscalationChain(User user,
                              HierarchicalUserRelationshipGraph graph)

Build a list of people upward in the hierarchical org from a given user.

Parameters:

user -

Returns:

An upwards chain of managers of the user. May return profile data.

getManager

User getManager(User user,
                HierarchicalUserRelationshipGraph graph)

Get a user's current manager in a hierarchical graph, or null if no manager is found.

Parameters:

user -

Returns:

The user's manager. May return profile data.

getColleagues

List<User> getColleagues(User user,
                         HierarchicalUserRelationshipGraph graph)

Get a list of a user's colleagues (people who report to the same manager, minus the user) (may return empty list, but not null).

Parameters:

user -

graph -

Returns:

A list of colleagues, sorted by name. May return profile data.

getDirectReports

List<User> getDirectReports(User manager,
                            HierarchicalUserRelationshipGraph graph)

Get a list of a user's direct reports (may return empty list, but not null).

Parameters:

manager -

graph -

Returns:

A list of direct reports, sorted by name. May return profile data.

getFriends

List<UserRelationshipView> getFriends(User user)

Get an list of a user's friends from the default mesh graph.

Parameters:

user -

Returns:

A list of friends, sorted by name. May return profile data.

getFriends

List<UserRelationshipView> getFriends(User user,
                                      MeshUserRelationshipGraph graph)

Get an list of a user's friends in a given mesh graph.

Parameters:

user -

graph -

Returns:

A list of friends, sorted by name. May return profile data.

getInverseFriends

List<UserRelationshipView> getInverseFriends(User user,
                                             MeshUserRelationshipGraph graph)

Get a list of who has friended a user, for a non-reflexive graph.

Parameters:

user -

graph -

Returns:

A list of friends, sorted by name. May return profile data.

isFriend

boolean isFriend(User user1,
                 User user2,
                 MeshUserRelationshipGraph graph)

In a reflexive mesh graph, are user1 and user2 friends? In a non-reflexive graph, is user1 following user2?

Parameters:

user1 -

user2 -

Returns:

getFriendRelationship

UserRelationship getFriendRelationship(User user1,
                                       User user2,
                                       MeshUserRelationshipGraph graph)

If two users have a relationship in a given graph, return it, else return null.

Parameters:

user1 -

user2 -

graph -

Returns:

getRelationshipListUsers

List<UserRelationshipView> getRelationshipListUsers(UserRelationshipList list)

Get a list of users from a user relationship list.

Parameters:

list -

Returns:

getAllActiveRelationships

Iterable<UserRelationshipView> getAllActiveRelationships(UserRelationshipManagerImpl.UserRelationshipResultFilter filter)

Get a list of active user relationships for a given graph (for admin console purposes).

Parameters:

filter - A filter for the results (by graph, username, etc).

getUserRelationshipCount

int getUserRelationshipCount()

Get a count of all UserRelationships.

Returns:

getUserRelationshipCount

int getUserRelationshipCount(UserRelationshipManagerImpl.UserRelationshipResultFilter filter)

Get a filtered count of all UserRelationships.

Parameters:

filter -

Returns:

createRelationshipList

UserRelationshipList createRelationshipList(String name,
                                            String label,
                                            User owner)

Create a new UserRelationshipList.

Parameters:

name - The name of the list.

owner - The list owner.

Returns:

A newly created list.

updateRelationshipList

void updateRelationshipList(UserRelationshipList list)

Update the name or labelStyle of a list. All child relationship changes will be persisted as well.

Parameters:

list - The list to update.

deleteRelationshipList

void deleteRelationshipList(UserRelationshipList list)

Delete a list and all child relationships from the DB.

Parameters:

list - The list to delete.

getRelationshipList

UserRelationshipList getRelationshipList(long listID)

Retrive a relationship list by ID.

Parameters:

listID - The ID of the list.

Returns:

the list, or null if none is found.

getRelationshipListsByOwner

Collection<UserRelationshipList> getRelationshipListsByOwner(User owner)

Retrieves a collection of lists based on an owner userID.

Parameters:

owner - The lists' owner.

Returns:

a Collection of lists, or an empty collection if none found.

getRelationshipListsByPerson

Collection<UserRelationshipList> getRelationshipListsByPerson(User person,
                                                              User owner)

Retrieves a collection of lists based on an owner userID and a person who is on the list.

Parameters:

owner - The lists' owner.

Returns:

a Collection of lists, or an empty collection if none found.

canViewRelationshipLists

boolean canViewRelationshipLists(User user)