com.atlassian.crowd.directory
Interface RemoteDirectory

All Superinterfaces:
Attributes
All Known Subinterfaces:
InternalRemoteDirectory, LDAPDirectory, SynchronisableDirectory
All Known Implementing Classes:
AbstractInternalDirectory, ApacheDS, ApacheDS15, AppleOpenDirectory, CachingDirectory, DbCachingRemoteDirectory, DelegatedAuthenticationDirectory, FedoraDS, GenericLDAP, InternalDirectory, MicrosoftActiveDirectory, NovelleDirectory, OpenDS, OpenLDAP, OpenLDAPRfc2307, RemoteCrowdDirectory, Rfc2307, RFC2307Directory, RFC4519Directory, SpringLDAPConnector, SunONE

public interface RemoteDirectory
extends Attributes

Gateway to perform operations on the physical remote directory.

Implementations will be provided an directoryId and Map of attributes.

Implementations of RemoteDirectory may throw an OperationNotSupportedException, if the operation is not supported, and the method declares that it may throw an OperationFailedException. Implementations should not knowingly throw a RuntimeException unless it really is a programming error - e.g. attempting to search for users using a group query.


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.
 RemoteDirectory getAuthoritativeDirectory()
           
 String getDescriptiveName()
          Returns a descriptive name for the type of directory.
 long getDirectoryId()
          Gets the internal unique directoryId of the directory store.
 Iterable<Membership> getMemberships()
          Get an iterable view of the available group memberships.
 boolean isGroupDirectGroupMember(String childGroup, String parentGroup)
          Determines if a group is a direct member of another group.
 boolean isRolesDisabled()
          Deprecated.  
 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.
<T> List<T>
searchGroupRelationships(MembershipQuery<T> query)
          Searches for membership information.
<T> List<T>
searchGroups(EntityQuery<T> query)
          Searches for groups that match the supplied query criteria.
<T> List<T>
searchUsers(EntityQuery<T> 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,Set<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,Set<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 supportsInactiveAccounts()
          Return true if this directory supports inactive users and groups.
 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.embedded.api.Attributes
getKeys, getValue, getValues, isEmpty
 

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 DirectoryImpl 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 Attributes

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

Parameters:
attributes - attributes map.

findUserByName

User findUserByName(String name)
                    throws UserNotFoundException,
                           OperationFailedException
Finds the user that matches the supplied name.

Parameters:
name - the name of the user (username).
Returns:
user entity.
Throws:
UserNotFoundException - a user with the supplied name does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

findUserWithAttributesByName

UserWithAttributes findUserWithAttributesByName(String name)
                                                throws UserNotFoundException,
                                                       OperationFailedException
Finds the user that matches the supplied name.

Parameters:
name - the name of the user (username).
Returns:
user entity with attributes.
Throws:
UserNotFoundException - a user with the supplied name does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

authenticate

User authenticate(String name,
                  PasswordCredential credential)
                  throws UserNotFoundException,
                         InactiveAccountException,
                         InvalidAuthenticationException,
                         ExpiredCredentialException,
                         OperationFailedException
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.
UserNotFoundException - The user wth the supplied name does not exist.
ExpiredCredentialException - The user's credentials have expired. The user must change their credentials in order to successfully authenticate.
OperationFailedException - underlying directory implementation failed to execute the operation.

addUser

User addUser(UserTemplate user,
             PasswordCredential credential)
             throws InvalidUserException,
                    InvalidCredentialException,
                    UserAlreadyExistsException,
                    OperationFailedException
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.
InvalidCredentialException - The supplied credential is invalid.
UserAlreadyExistsException - The user already exists
OperationFailedException - underlying directory implementation failed to execute the operation.

updateUser

User updateUser(UserTemplate user)
                throws InvalidUserException,
                       UserNotFoundException,
                       OperationFailedException
Updates the user.

Parameters:
user - The user to update.
Returns:
the updated user retrieved from the underlying store.
Throws:
UserNotFoundException - the user does not exist in the directory store.
InvalidUserException - the supplied user is invalid.
OperationFailedException - underlying directory implementation failed to execute the operation.

updateUserCredential

void updateUserCredential(String username,
                          PasswordCredential credential)
                          throws UserNotFoundException,
                                 InvalidCredentialException,
                                 OperationFailedException
Updates the password for a user.

Parameters:
username - The name of the user (username).
credential - The new credential (password).
Throws:
UserNotFoundException - The user does not exist.
InvalidCredentialException - The supplied credential is invalid.
OperationFailedException - underlying directory implementation failed to execute the operation.

renameUser

User renameUser(String oldName,
                String newName)
                throws UserNotFoundException,
                       InvalidUserException,
                       UserAlreadyExistsException,
                       OperationFailedException
Renames a user.

Parameters:
oldName - name of existing user.
newName - desired name of user.
Returns:
renamed user.
Throws:
UserNotFoundException - if the user with the existing name does not exist.
InvalidUserException - if the new username is invalid.
UserAlreadyExistsException - if the newName already exists.
OperationFailedException - if the underlying directory implementation failed to execute the operation.

storeUserAttributes

void storeUserAttributes(String username,
                         Map<String,Set<String>> attributes)
                         throws UserNotFoundException,
                                OperationFailedException
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

Attributes with values of empty sets are not added (these attributes are effectively removed).

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:
UserNotFoundException - user with supplied username does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

removeUserAttributes

void removeUserAttributes(String username,
                          String attributeName)
                          throws UserNotFoundException,
                                 OperationFailedException
Removes all the values for a single attribute key for a user. If the attribute key does not exist nothing will happen.

Parameters:
username - name of the user to update.
attributeName - name of attribute to remove.
Throws:
UserNotFoundException - user with supplied username does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

removeUser

void removeUser(String name)
                throws UserNotFoundException,
                       OperationFailedException
Removes the user that matches the supplied name.

Parameters:
name - The name of the user (username).
Throws:
UserNotFoundException - The user does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

searchUsers

<T> List<T> searchUsers(EntityQuery<T> query)
                    throws OperationFailedException
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.
Throws:
OperationFailedException - if the underlying directory implementation failed to execute the operation
IllegalArgumentException - if the query is not a valid user query

findGroupByName

Group findGroupByName(String name)
                      throws GroupNotFoundException,
                             OperationFailedException
Finds the group that matches the supplied name.

Parameters:
name - the name of the group.
Returns:
group entity.
Throws:
GroupNotFoundException - a group with the supplied name does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

findGroupWithAttributesByName

GroupWithAttributes findGroupWithAttributesByName(String name)
                                                  throws GroupNotFoundException,
                                                         OperationFailedException
Finds the group that matches the supplied name.

Parameters:
name - the name of the group.
Returns:
group entity with attributes.
Throws:
GroupNotFoundException - a group with the supplied name does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

addGroup

Group addGroup(GroupTemplate group)
               throws InvalidGroupException,
                      OperationFailedException
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.
OperationFailedException - underlying directory implementation failed to execute the operation.

updateGroup

Group updateGroup(GroupTemplate group)
                  throws InvalidGroupException,
                         GroupNotFoundException,
                         ReadOnlyGroupException,
                         OperationFailedException
Updates the group.

Parameters:
group - The group to update.
Returns:
the updated group retrieved from the underlying store.
Throws:
GroupNotFoundException - the group does not exist in the directory store.
InvalidGroupException - the supplied group is invalid.
ReadOnlyGroupException - the group is read-only
OperationFailedException - underlying directory implementation failed to execute the operation.

renameGroup

Group renameGroup(String oldName,
                  String newName)
                  throws GroupNotFoundException,
                         InvalidGroupException,
                         OperationFailedException
Renames a group.

Parameters:
oldName - name of existing group.
newName - desired name of group.
Returns:
renamed group.
Throws:
GroupNotFoundException - if the group with the existing name does not exist.
InvalidGroupException - if the new groupname is invalid or already exists in the directory.
OperationFailedException - if the underlying directory implementation failed to execute the operation.

storeGroupAttributes

void storeGroupAttributes(String groupName,
                          Map<String,Set<String>> attributes)
                          throws GroupNotFoundException,
                                 OperationFailedException
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

Attributes with values of empty sets are not added (these attributes are effectively removed).

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:
GroupNotFoundException - group with supplied groupName does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

removeGroupAttributes

void removeGroupAttributes(String groupName,
                           String attributeName)
                           throws GroupNotFoundException,
                                  OperationFailedException
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:
GroupNotFoundException - group with supplied groupName does not exist.
OperationFailedException - underlying directory implementation failed to execute the operation.

removeGroup

void removeGroup(String name)
                 throws GroupNotFoundException,
                        ReadOnlyGroupException,
                        OperationFailedException
Removes the group that matches the supplied name.

Parameters:
name - The name of the group.
Throws:
GroupNotFoundException - The group does not exist.
ReadOnlyGroupException - if the group is read-only and not allowed to be deleted.
OperationFailedException - underlying directory implementation failed to execute the operation.

searchGroups

<T> List<T> searchGroups(EntityQuery<T> query)
                     throws OperationFailedException
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.
Throws:
OperationFailedException - if the underlying directory implementation failed to execute the operation
IllegalArgumentException - if the query is not a valid group query

isUserDirectGroupMember

boolean isUserDirectGroupMember(String username,
                                String groupName)
                                throws OperationFailedException
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.
Throws:
OperationFailedException - underlying directory implementation failed to execute the operation.

isGroupDirectGroupMember

boolean isGroupDirectGroupMember(String childGroup,
                                 String parentGroup)
                                 throws OperationFailedException
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.
Throws:
OperationFailedException - underlying directory implementation failed to execute the operation.

addUserToGroup

void addUserToGroup(String username,
                    String groupName)
                    throws GroupNotFoundException,
                           UserNotFoundException,
                           ReadOnlyGroupException,
                           OperationFailedException
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:
GroupNotFoundException - If the group cannot be found.
UserNotFoundException - If the user cannot be found.
ReadOnlyGroupException - If the group is read-only
OperationFailedException - underlying directory implementation failed to execute the operation.

addGroupToGroup

void addGroupToGroup(String childGroup,
                     String parentGroup)
                     throws GroupNotFoundException,
                            InvalidMembershipException,
                            ReadOnlyGroupException,
                            OperationFailedException
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:
GroupNotFoundException - One or both of the groups cannot be found.
InvalidMembershipException - if the childGroup and parentGroup exist but are of different GroupTypes.
ReadOnlyGroupException - if either of the groups are read-only
OperationFailedException - underlying directory implementation failed to execute the operation.

removeUserFromGroup

void removeUserFromGroup(String username,
                         String groupName)
                         throws GroupNotFoundException,
                                UserNotFoundException,
                                MembershipNotFoundException,
                                ReadOnlyGroupException,
                                OperationFailedException
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:
GroupNotFoundException - If the group cannot be found.
UserNotFoundException - If the user cannot be found.
MembershipNotFoundException - if the user is not a direct member of the group.
ReadOnlyGroupException - if the group is read-only
OperationFailedException - underlying directory implementation failed to execute the operation.

removeGroupFromGroup

void removeGroupFromGroup(String childGroup,
                          String parentGroup)
                          throws GroupNotFoundException,
                                 InvalidMembershipException,
                                 MembershipNotFoundException,
                                 ReadOnlyGroupException,
                                 OperationFailedException
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:
GroupNotFoundException - 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.
ReadOnlyGroupException - if the groups are read-only
OperationFailedException - underlying directory implementation failed to execute the operation.

searchGroupRelationships

<T> List<T> searchGroupRelationships(MembershipQuery<T> query)
                                 throws OperationFailedException
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.
Throws:
OperationFailedException - underlying directory implementation failed to execute the operation.
IllegalArgumentException - if the query is not a valid membership query

testConnection

void testConnection()
                    throws OperationFailedException
Test if a connection to the directory server can be established.

Throws:
OperationFailedException - underlying directory implementation failed to execute the operation.

supportsInactiveAccounts

boolean supportsInactiveAccounts()
Return true if this directory supports inactive users and groups.

Currently inactive users and groups are not supported for LDAP directories.

Returns:
true if the directory supports inactive users and groups

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.

isRolesDisabled

boolean isRolesDisabled()
Deprecated. 

Expose whether the directory has roles disabled. Always true.

Returns:
true

getMemberships

Iterable<Membership> getMemberships()
                                    throws OperationFailedException

Get an iterable view of the available group memberships. This may be implemented as a single remote call or separate calls, depending on the directory.

If there is a failure in the underlying retrieval, the iterator may throw Membership.MembershipIterationException at runtime.

If the directory does not have a bulk call interface then a typical implementation would be:

 return new DirectoryMembershipsIterable(this);
 
 

Returns:
an iterable view of the available group memberships
Throws:
OperationFailedException - if the underlying directory implementation failed to execute the operation

getAuthoritativeDirectory

RemoteDirectory getAuthoritativeDirectory()
Returns:
the directory that is the authoritative source of data for this directory, possibly itself.


Copyright © 2012 Atlassian. All Rights Reserved.