com.atlassian.crowd.integration.directory
Interface RemoteDirectory

All Superinterfaces:

AttributeAware

All Known Subinterfaces:

BatchingRemoteDirectory, LDAPDirectory

All Known Implementing Classes:

ApacheDS, ApacheDS15, AppleOpenDirectory, CachingLDAPDirectory, DelegatedAuthenticationDirectory, FedoraDS, GenericLDAP, InternalDirectory, MicrosoftActiveDirectory, NovelleDirectory, OpenDS, OpenLDAP, OpenLDAPRfc2307, Rfc2307, RFC2307Directory, RFC4519Directory, SpringLDAPConnector, SunONE

public interface RemoteDirectory
extends AttributeAware

Gateway to perform operations on the physical remote directory.

Implementations will be provided an directoryId and Map of attributes.

Method Summary

Group	addGroup(GroupTemplate group) Adds a group to the directory store.
void	addGroupToGroup(String childGroup, String parentGroup) Adds a group as a member of a parent group.
User	addUser(UserTemplate user, PasswordCredential credential) Adds a user to the directory store.
void	addUserToGroup(String username, String groupName) Adds a user as a member of a group.
User	authenticate(String name, PasswordCredential credential) Authenticates a user with the directory store.
Group	findGroupByName(String name) Finds the group that matches the supplied name.
GroupWithAttributes	findGroupWithAttributesByName(String name) Finds the group that matches the supplied name.
User	findUserByName(String name) Finds the user that matches the supplied name.
UserWithAttributes	findUserWithAttributesByName(String name) Finds the user that matches the supplied name.
String	getDescriptiveName() Returns a descriptive name for the type of directory.
long	getDirectoryId() Gets the internal unique directoryId of the directory store.
boolean	isGroupDirectGroupMember(String childGroup, String parentGroup) Determines if a group is a direct member of another group.
boolean	isUserDirectGroupMember(String username, String groupName) Determines if a user is a direct member of a group.
void	removeGroup(String name) Removes the group that matches the supplied name.
void	removeGroupAttributes(String groupName, String attributeName) Removes all the values for a single attribute key for a group.
void	removeGroupFromGroup(String childGroup, String parentGroup) Removes a group as a member of a parent group.
void	removeUser(String name) Removes the user that matches the supplied name.
void	removeUserAttributes(String username, String attributeName) Removes all the values for a single attribute key for a user.
void	removeUserFromGroup(String username, String groupName) Removes a user as a member of a group.
Group	renameGroup(String oldName, String newName) Renames a group.
User	renameUser(String oldName, String newName) Renames a user.
List	searchGroupRelationships(MembershipQuery query) Searches for membership information.
List	searchGroups(EntityQuery query) Searches for groups that match the supplied query criteria.
List	searchUsers(EntityQuery query) Searches for users that match the supplied query criteria.
void	setAttributes(Map<String,String> attributes) When a directory store is loaded, the attributes map will be set by the Crowd framework.
void	setDirectoryId(long directoryId) When a directory store is loaded, the directoryId will be set by the crowd framework.
void	storeGroupAttributes(String groupName, Map<String,List<String>> attributes) Adds or updates a group's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.
void	storeUserAttributes(String username, Map<String,List<String>> attributes) Adds or updates a user's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.
boolean	supportsNestedGroups() Allows us to only display nested-group related UI for directories that support it.
void	testConnection() Test if a connection to the directory server can be established.
Group	updateGroup(GroupTemplate group) Updates the group.
User	updateUser(UserTemplate user) Updates the user.
void	updateUserCredential(String username, PasswordCredential credential) Updates the password for a user.

Methods inherited from interface com.atlassian.crowd.integration.model.AttributeAware

getAttribute, getAttributeNames, getAttributes, hasAttribute

Method Detail

getDirectoryId

long getDirectoryId()

Gets the internal unique directoryId of the directory store.

Returns:

The directoryId.

setDirectoryId

void setDirectoryId(long directoryId)

When a directory store is loaded, the directoryId will be set by the crowd framework.

Parameters:

directoryId - The unique directoryId of the Directory stored in the database.

getDescriptiveName

String getDescriptiveName()

Returns a descriptive name for the type of directory.

Returns:

descriptive name.

setAttributes

void setAttributes(Map<String,String> attributes)

When a directory store is loaded, the attributes map will be set by the Crowd framework. Implementations may store a reference to this map in order to implement the AttributeAware

The Map is immutable and implementations are required to maintain immutability.

Parameters:

attributes - attributes map.

findUserByName

User findUserByName(String name)
                    throws ObjectNotFoundException

Finds the user that matches the supplied name.

Parameters:

name - the name of the user (username).

Returns:

user entity.

Throws:

ObjectNotFoundException - a user with the supplied name does not exist.

findUserWithAttributesByName

UserWithAttributes findUserWithAttributesByName(String name)
                                                throws ObjectNotFoundException

Finds the user that matches the supplied name.

Parameters:

name - the name of the user (username).

Returns:

user entity with attributes.

Throws:

ObjectNotFoundException - a user with the supplied name does not exist.

authenticate

User authenticate(String name,
                  PasswordCredential credential)
                  throws ObjectNotFoundException,
                         InactiveAccountException,
                         InvalidAuthenticationException

Authenticates a user with the directory store.

Parameters:

name - The name of the user (username).

credential - The supplied credentials (password).

Returns:

The populated user if the authentication is valid.

Throws:

InactiveAccountException - The supplied user is inactive.

InvalidAuthenticationException - Authentication with the provided credentials failed.

ObjectNotFoundException - The user wth the supplied name does not exist.

addUser

User addUser(UserTemplate user,
             PasswordCredential credential)
             throws InvalidUserException,
                    ObjectNotFoundException,
                    InvalidCredentialException

Adds a user to the directory store.

Parameters:

user - template of the user to add.

credential - password. May be null, since JIRA creates a user in two steps (user THEN password)

Returns:

the added user retrieved from the underlying store.

Throws:

InvalidUserException - The supplied user is invalid.

ObjectNotFoundException - The user could not be looked up after creation or the directory with the ID of user.directoryId does not exist.

InvalidCredentialException - The supplied credential is invalid.

updateUser

User updateUser(UserTemplate user)
                throws InvalidUserException,
                       ObjectNotFoundException

Updates the user.

Parameters:

user - The user to update.

Returns:

the updated user retrieved from the underlying store.

Throws:

ObjectNotFoundException - the user does not exist in the directory store.

InvalidUserException - the supplied user is invalid.

updateUserCredential

void updateUserCredential(String username,
                          PasswordCredential credential)
                          throws ObjectNotFoundException,
                                 InvalidCredentialException

Updates the password for a user.

Parameters:

username - The name of the user (username).

credential - The new credential (password).

Throws:

ObjectNotFoundException - The user does not exist.

InvalidCredentialException - The supplied credential is invalid.

renameUser

User renameUser(String oldName,
                String newName)
                throws ObjectNotFoundException,
                       InvalidUserException

Renames a user.

Parameters:

oldName - name of existing user.

newName - desired name of user.

Returns:

renamed user.

Throws:

ObjectNotFoundException - if the user with the existing name does not exist.

InvalidUserException - if the new username is invalid or already exists in the directory.

storeUserAttributes

void storeUserAttributes(String username,
                         Map<String,List<String>> attributes)
                         throws ObjectNotFoundException

Adds or updates a user's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.

The attributes map represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing

Parameters:

username - name of user to update.

attributes - new or updated attributes (attributes that don't need changing should not appear in this Map).

Throws:

ObjectNotFoundException - user with supplied username does not exist.

removeUserAttributes

void removeUserAttributes(String username,
                          String attributeName)
                          throws ObjectNotFoundException

Removes all the values for a single attribute key for a user.

Parameters:

username - name of the user to update.

attributeName - name of attribute to remove.

Throws:

ObjectNotFoundException - user with supplied username does not exist.

removeUser

void removeUser(String name)
                throws ObjectNotFoundException

Removes the user that matches the supplied name.

Parameters:

name - The name of the user (username).

Throws:

ObjectNotFoundException - The user does not exist.

searchUsers

List searchUsers(EntityQuery query)

Searches for users that match the supplied query criteria.

Parameters:

query - EntityQuery for Entity.USER.

Returns:

List<User> or List<String> of users/usernames matching the search criteria. An empty List will be returned if no users matching the criteria are found.

findGroupByName

Group findGroupByName(String name)
                      throws ObjectNotFoundException

Finds the group that matches the supplied name.

Parameters:

name - the name of the group.

Returns:

group entity.

Throws:

ObjectNotFoundException - a group with the supplied name does not exist.

findGroupWithAttributesByName

GroupWithAttributes findGroupWithAttributesByName(String name)
                                                  throws ObjectNotFoundException

Finds the group that matches the supplied name.

Parameters:

name - the name of the group.

Returns:

group entity with attributes.

Throws:

ObjectNotFoundException - a group with the supplied name does not exist.

addGroup

Group addGroup(GroupTemplate group)
               throws InvalidGroupException,
                      ObjectNotFoundException

Adds a group to the directory store.

Parameters:

group - template of the group to add.

Returns:

the added group retrieved from the underlying store.

Throws:

InvalidGroupException - The supplied group is invalid.

ObjectNotFoundException - The group could not be looked up after creation or the directory with the ID of group.directoryId does not exist.

updateGroup

Group updateGroup(GroupTemplate group)
                  throws InvalidGroupException,
                         ObjectNotFoundException

Updates the group.

Parameters:

group - The group to update.

Returns:

the updated group retrieved from the underlying store.

Throws:

ObjectNotFoundException - the group does not exist in the directory store.

InvalidGroupException - the supplied group is invalid.

renameGroup

Group renameGroup(String oldName,
                  String newName)
                  throws ObjectNotFoundException,
                         InvalidGroupException

Renames a group.

Parameters:

oldName - name of existing group.

newName - desired name of group.

Returns:

renamed group.

Throws:

ObjectNotFoundException - if the group with the existing name does not exist.

InvalidGroupException - if the new groupname is invalid or already exists in the directory.

storeGroupAttributes

void storeGroupAttributes(String groupName,
                          Map<String,List<String>> attributes)
                          throws ObjectNotFoundException

Adds or updates a group's attributes with the new Map of attribute values in the directory specified by the passed in directoryId.

The attributes map represents new or updated attributes and does not replace existing attributes unless the key of an attribute matches the key of an existing

Parameters:

groupName - name of group to update.

attributes - new or updated attributes (attributes that don't need changing should not appear in this Map).

Throws:

ObjectNotFoundException - group with supplied groupName does not exist.

removeGroupAttributes

void removeGroupAttributes(String groupName,
                           String attributeName)
                           throws ObjectNotFoundException

Removes all the values for a single attribute key for a group.

Parameters:

groupName - name of the group to update.

attributeName - name of attribute to remove.

Throws:

ObjectNotFoundException - group with supplied groupName does not exist.

removeGroup

void removeGroup(String name)
                 throws ObjectNotFoundException

Removes the group that matches the supplied name.

Parameters:

name - The name of the group.

Throws:

ObjectNotFoundException - The group does not exist.

searchGroups

List searchGroups(EntityQuery query)

Searches for groups that match the supplied query criteria.

Parameters:

query - EntityQuery for Entity.GROUP.

Returns:

List or List of groups/groupnames matching the search criteria. An empty List will be returned if no groups matching the criteria are found.

isUserDirectGroupMember

boolean isUserDirectGroupMember(String username,
                                String groupName)

Determines if a user is a direct member of a group. The directory is NOT expected to resolve any transitive group relationships.

Parameters:

username - name of user.

groupName - name of group.

Returns:

true iff the user is a direct member of the group.

isGroupDirectGroupMember

boolean isGroupDirectGroupMember(String childGroup,
                                 String parentGroup)

Determines if a group is a direct member of another group. The directory is NOT expected to resolve any transitive group relationships.

Parameters:

childGroup - name of child group.

parentGroup - name of parent group.

Returns:

true iff the childGroup is a direct member of the parentGroup.

addUserToGroup

void addUserToGroup(String username,
                    String groupName)
                    throws ObjectNotFoundException

Adds a user as a member of a group. This means that all user members of childGroup will appear as members of parentGroup to querying applications.

Parameters:

username - The user that will become a member of groupName

groupName - The group that will gain a new member.

Throws:

ObjectNotFoundException - If the user or group cannot be found.

addGroupToGroup

void addGroupToGroup(String childGroup,
                     String parentGroup)
                     throws ObjectNotFoundException,
                            InvalidMembershipException

Adds a group as a member of a parent group.

Parameters:

parentGroup - The group that will gain a new member

childGroup - The group that will become a member of parentGroup

Throws:

ObjectNotFoundException - One or both of the groups cannot be found.

InvalidMembershipException - if the childGroup and parentGroup exist but are of different GroupTypes.

removeUserFromGroup

void removeUserFromGroup(String username,
                         String groupName)
                         throws ObjectNotFoundException,
                                MembershipNotFoundException

Removes a user as a member of a group.

Parameters:

groupName - The group that will lose the member.

username - The user that will be removed from parentGroup

Throws:

ObjectNotFoundException - If either the user or group cannot be found.

MembershipNotFoundException - if the user is not a direct member of the group.

removeGroupFromGroup

void removeGroupFromGroup(String childGroup,
                          String parentGroup)
                          throws ObjectNotFoundException,
                                 InvalidMembershipException,
                                 MembershipNotFoundException

Removes a group as a member of a parent group.

Parameters:

parentGroup - The group that will lose the member.

childGroup - The group that will be removed from parentGroup

Throws:

ObjectNotFoundException - One or both of the groups cannot be found.

InvalidMembershipException - if the childGroup and parentGroup exist but are of different GroupTypes.

MembershipNotFoundException - if the childGroup is not a direct member of the parentGroup.

searchGroupRelationships

List searchGroupRelationships(MembershipQuery query)

Searches for membership information.

Parameters:

query - query for memberships.

Returns:

a List of Users or Groups or Strings depending on the query criteria. An empty List if there are no results.

testConnection

void testConnection()
                    throws DirectoryAccessException

Test if a connection to the directory server can be established.

Throws:

DirectoryAccessException - An unknown wire exception occurred.

supportsNestedGroups

boolean supportsNestedGroups()

Allows us to only display nested-group related UI for directories that support it.

Returns:

true if the directory can handle having a group added to a group.