com.atlassian.crowd.integration.directory.cache
Interface DirectoryCache

All Superinterfaces:

com.atlassian.event.EventListener

All Known Implementing Classes:

DefaultDirectoryCache, LDAPDirectoryCache, MicrosoftActiveDirectoryCache

public interface DirectoryCache
extends com.atlassian.event.EventListener

Event-driven cache of directory entities and relationships. ALL DirectoryCache implementations must have a constructor that matches the following type signature: (long directoryID, net.sf.ehcache.CacheManager ehcacheManager, int maxElementsInMemoryPerSubCache) This is so that the Cache can be constructed via reflection. Implementations are required to be threadsafe.

Method Summary

void	clear() Clear the contents of the entire cache.
void	close() Close the cache and render it unuseable.
List<String>	getAllGroupNames() Retrieves the complete collection of all group names for the cached directory or null if the complete list is not cached.
List<String>	getAllUserNames() Retrieves the complete collection of all user names for the cached directory or null if the complete list is not cached.
Group	getGroup(String groupName) Returns the cached Group matching the directoryID and groupName.
List<String>	getGroupMembershipsOfGroup(String groupName) Returns a list of group membership names for a particular group.
List<String>	getGroupMembershipsOfUser(String username) Returns a list of group membership names for a particular user.
List<String>	getGroupMembersOfGroup(String groupName) Returns a list of child group member names for a particular group.
DirectoryCacheStatistics	getStatistics() Provides access to some statistics for the cache.
User	getUser(String username) Returns the cached User matching the directoryID and username.
List<String>	getUserMembersOfGroup(String groupName) Returns a list of user member names for a particular group.
Boolean	isGroupGroupMember(String childGroup, String parentGroup) Determines if a childGroup is a direct member of a parentGroup.
Boolean	isUserGroupMember(String username, String groupName) Determines if a user is a direct member of a group.
void	removeGroup(String groupName) Removes a group (if it exists in the cache), along with any existing relationships of the group to users or groups.
void	removeGroupAsGroupMember(String childGroup, String parentGroup) Stores the fact that the childGroup is not a direct member of a parentGroup.
void	removeUser(String username) Removes a user (if it exists in the cache), along with any existing relationships of the user to groups or roles.
void	removeUserAsGroupMember(String username, String groupName) Stores the fact that the user is not a direct member of a group.
void	setGroupAsGroupMember(String childGroup, String parentGroup) Stores the fact that the childGroup is a direct member of a parentGroup.
void	setUserAsGroupMember(String username, String groupName) Stores the fact that the user is a direct member of a group.
void	storeAllGroupNames(List<String> groupNames) Store a complete list of all group names for the cached directory.
void	storeAllUserNames(List<String> usernames) Store a complete list of all user names for the cached directory.
void	storeGroup(Group group) Stores a clone of the supplied group object in the cache.
void	storeGroupMembershipsOfGroup(String groupName, Collection<String> parentGroupNames) Stores a list of direct group membership names for a particular group.
void	storeGroupMembershipsOfUser(String username, Collection<String> groupNames) Stores a list of direct group membership names for a particular user.
void	storeGroupMembersOfGroup(String groupName, Collection<String> childGroupNames, boolean complete) Stores a list of group member names for a particular group.
void	storeUser(User user) Stores a clone of the supplied user object in the cache.
void	storeUserMembersOfGroup(String groupName, Collection<String> usernames, boolean complete) Stores a list of user member names for a particular group.

Methods inherited from interface com.atlassian.event.EventListener

getHandledEventClasses, handleEvent

Method Detail

getUser

User getUser(String username)
             throws ObjectNotFoundException

Returns the cached User matching the directoryID and username. If no user has been cached, null is returned. This signifies we do not know whether the user exists or not. If it is known that the user does not exist, an ObjectNotFoundException is thrown. For example, if a user is removed, a subsequent getUser call attempting to find the removed user will throw this exception. The returning user is a clone of user object in the cache. Callers are free to mutate the clone however they want.

Parameters:

username - name of user to find.

Returns:

a clone of the cached user, if one exists, otherwise null.

Throws:

ObjectNotFoundException - if the object does not exist.

getAllUserNames

List<String> getAllUserNames()

Retrieves the complete collection of all user names for the cached directory or null if the complete list is not cached.

Returns:

complete list of all user names or null if the complete list is not cached.

storeAllUserNames

void storeAllUserNames(List<String> usernames)

Store a complete list of all user names for the cached directory.

Parameters:

usernames - complete list of all user names.

storeUser

void storeUser(User user)

Stores a clone of the supplied user object in the cache. If a user with the same name already exists in the cache, then it is silently replaced.

Parameters:

user - user to cache.

removeUser

void removeUser(String username)

Removes a user (if it exists in the cache), along with any existing relationships of the user to groups or roles. The cache entry will be marked so that subsequent calls to getUser(username) will throw an ObjectNotFoundException.

Parameters:

username - name of user to remove from cache.

getGroup

Group getGroup(String groupName)
               throws ObjectNotFoundException

Returns the cached Group matching the directoryID and groupName. If no group has been cached, null is returned. This signifies we do not know whether the group exists or not. If it is known that the group does not exist, an ObjectNotFoundException is thrown. For example, if a group is removed, a subsequent getGroup call attempting to find the removed group will throw this exception. The returning group is a clone of group object in the cache. Callers are free to mutate the clone however they want.

Parameters:

groupName - name of group to find.

Returns:

a clone of the cached group, if one exists, otherwise null.

Throws:

ObjectNotFoundException - if the object does not exist.

getAllGroupNames

List<String> getAllGroupNames()

Retrieves the complete collection of all group names for the cached directory or null if the complete list is not cached.

Returns:

complete list of all group names or null if the complete list is not cached.

storeAllGroupNames

void storeAllGroupNames(List<String> groupNames)

Store a complete list of all group names for the cached directory.

Parameters:

groupNames - complete list of all group names.

storeGroup

void storeGroup(Group group)

Stores a clone of the supplied group object in the cache. If a group with the same name already exists in the cache, then it is silently replaced.

Parameters:

group - group to cache.

removeGroup

void removeGroup(String groupName)

Removes a group (if it exists in the cache), along with any existing relationships of the group to users or groups. The cache entry will be marked so that subsequent calls to getGroup(groupName) will throw an ObjectNotFoundException.

Parameters:

groupName - name of group to remove from cache.

getUserMembersOfGroup

List<String> getUserMembersOfGroup(String groupName)

Returns a list of user member names for a particular group. The list reflects the complete, direct user members set for the group. If the cache does not have a complete set in memory (eg. it has a partial set), null is returned.

Parameters:

groupName - name of group to lookup.

Returns:

complete list of direct user member names OR null.

storeUserMembersOfGroup

void storeUserMembersOfGroup(String groupName,
                             Collection<String> usernames,
                             boolean complete)

Stores a list of user member names for a particular group. If and only if the complete parameter is set to true, the collection of user names is assumed to be the complete collection of direct user members of the group. The usernames is allowed to be incomplete ONLY IF the missing usernames are not stored in the cache at all (ie. the entities are not stored / the entities membership information is not stored). Therefore the usernames ALWAYS represents the COMPLETE list of members the cache knows about (regardless of the "complete" flag). The "complete" flag denotes that the collection is the complete list of usernames in the entire directory for the group.

Parameters:

groupName - name of the group.

usernames - collection of direct user members of the group.

complete - true if and only if the collection of direct user member names reflects the complete set of direct user members.

getGroupMembershipsOfUser

List<String> getGroupMembershipsOfUser(String username)

Returns a list of group membership names for a particular user. The list reflects the complete, direct group membership set for the user. If the cache does not have a complete set in memory (eg. it has a partial set), null is returned.

Parameters:

username - name of user to lookup.

Returns:

complete list of direct group membership names OR null.

storeGroupMembershipsOfUser

void storeGroupMembershipsOfUser(String username,
                                 Collection<String> groupNames)

Stores a list of direct group membership names for a particular user. The collection of group names is assumed to be the complete collection of direct group memberships of the user.

Parameters:

username - name of the user.

groupNames - collection of direct group memberships of the user. group membership names reflects the complete set of direct group memberships.

isUserGroupMember

Boolean isUserGroupMember(String username,
                          String groupName)

Determines if a user is a direct member of a group.

Parameters:

username - name of user.

groupName - name of group.

Returns:

true iff the user is a direct member of the group, false iff the user is not a direct member of the group, null iff there is insufficient information in the cache to determine whether the user is a direct member of the group or not.

setUserAsGroupMember

void setUserAsGroupMember(String username,
                          String groupName)

Stores the fact that the user is a direct member of a group.

Parameters:

username - name of user.

groupName - name of group.

removeUserAsGroupMember

void removeUserAsGroupMember(String username,
                             String groupName)

Stores the fact that the user is not a direct member of a group.

Parameters:

username - name of user.

groupName - name of group.

getGroupMembersOfGroup

List<String> getGroupMembersOfGroup(String groupName)

Returns a list of child group member names for a particular group. The list reflects the complete, direct child group members set for the group. If the cache does not have a complete set in memory (eg. it has a partial set), null is returned.

Parameters:

groupName - name of parent group to lookup.

Returns:

complete list of direct child group member names OR null.

storeGroupMembersOfGroup

void storeGroupMembersOfGroup(String groupName,
                              Collection<String> childGroupNames,
                              boolean complete)

Stores a list of group member names for a particular group. If and only if the complete parameter is set to true, the collection of group names is assumed to be the complete collection of direct group members of the group. The childGroupNames is allowed to be incomplete ONLY IF the missing childGroupNames are not stored in the cache at all (ie. the entities are not stored / the entities membership information is not stored). Therefore the childGroupNames ALWAYS represents the COMPLETE list of members the cache knows about (regardless of the "complete" flag). The "complete" flag denotes that the collection is the complete list of childGroupNames in the entire directory for the group.

Parameters:

groupName - name of the group.

childGroupNames - collection of direct group members of the group.

complete - true if and only if the collection of direct group member names reflects the complete set of direct group members.

getGroupMembershipsOfGroup

List<String> getGroupMembershipsOfGroup(String groupName)

Returns a list of group membership names for a particular group. The list reflects the complete, direct group membership set for the group. If the cache does not have a complete set in memory (eg. it has a partial set), null is returned.

Parameters:

groupName - name of group to lookup.

Returns:

complete list of direct group membership names OR null.

storeGroupMembershipsOfGroup

void storeGroupMembershipsOfGroup(String groupName,
                                  Collection<String> parentGroupNames)

Stores a list of direct group membership names for a particular group. The collection of group names is assumed to be the complete collection of direct parent group memberships of the child group.

Parameters:

groupName - name of the child group.

parentGroupNames - collection of direct group memberships of the child group. group membership names reflects the complete set of direct group memberships.

isGroupGroupMember

Boolean isGroupGroupMember(String childGroup,
                           String parentGroup)

Determines if a childGroup is a direct member of a parentGroup.

Parameters:

childGroup - name of child group.

parentGroup - name of parent group.

Returns:

true iff the childGroup is a direct member of the parentGroup, false iff the childGroup is not a direct member of the parentGroup, null iff there is insufficient information in the cache to determine whether the childGroup is a direct member of the parentGroup or not.

setGroupAsGroupMember

void setGroupAsGroupMember(String childGroup,
                           String parentGroup)

Stores the fact that the childGroup is a direct member of a parentGroup.

Parameters:

childGroup - name of child group.

parentGroup - name of parent group.

removeGroupAsGroupMember

void removeGroupAsGroupMember(String childGroup,
                              String parentGroup)

Stores the fact that the childGroup is not a direct member of a parentGroup.

Parameters:

childGroup - name of child group.

parentGroup - name of parent group.

clear

void clear()

Clear the contents of the entire cache. All entities and relationships will be removed.

close

void close()

Close the cache and render it unuseable.

getStatistics

DirectoryCacheStatistics getStatistics()

Provides access to some statistics for the cache.

Returns: