com.atlassian.crowd.embedded.api
Interface CrowdDirectoryService

All Known Implementing Classes:

CrowdDirectoryServiceImpl

public interface CrowdDirectoryService

Provides the interface for performing Directory Operations in Crowd for applications embedding Crowd. Null parameters for methods may throw NullPointerException or IllegalArgumentException.

Method Summary

Directory	addDirectory(Directory directory) Will add a new Directory into the local database.
List<Directory>	findAllDirectories() Will return a List<Directory> ordered by the order specified by the application.
Directory	findDirectoryById(long directoryId) Will return a Directory based on the given directoryId
DirectorySynchronisationInformation	getDirectorySynchronisationInformation(long directoryId) Returns the synchronisation information for the directory.
ConnectionPoolProperties	getStoredConnectionPoolProperties() Retrieves the stored LDAP connection pool properties which will be applied when the system restarts.
ConnectionPoolProperties	getSystemConnectionPoolProperties() Retrieves the system LDAP connection pool properties (i.e.
boolean	isDirectorySynchronisable(long directoryId) Returns true if the underlying directory implementation supports manual synchronisation of the directory's local cache.
boolean	isDirectorySynchronising(long directoryId) Returns true if the given Directory is currently synchronising.
boolean	removeDirectory(long directoryId) Will remove a directory from the Application, this will also remove all associated entities (users/groups/memberships).
void	setConnectionPoolProperties(ConnectionPoolProperties poolProperties) Stores the provided LDAP connection pool properties so they can be applied when the system next restarts.
void	setDirectoryPosition(long directoryId, int position) Will place the directory with the given directoryId and the passed in position in the current list of directories configured for an application.
boolean	supportsNestedGroups(long directoryId) Returns true if the underlying directory implementation supports nested groups.
void	synchroniseDirectory(long directoryId) Requests that this directory should update its cache by synchronising with the remote server.
void	synchroniseDirectory(long directoryId, boolean runInBackground) Requests that this directory should update its cache by synchronising with the remote server.
void	testConnection(Directory directory) Test if a connection to the directory server can be established.
Directory	updateDirectory(Directory directory) Will update the Directory.

Method Detail

addDirectory

Directory addDirectory(Directory directory)
                       throws OperationFailedException

Will add a new Directory into the local database.

Parameters:

directory - The directory to be saved

Returns:

the persisted Directory

Throws:

OperationFailedException - if the operation failed for any reason

testConnection

void testConnection(Directory directory)
                    throws OperationFailedException

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

Parameters:

directory - Directory to test

Throws:

OperationFailedException - underlying directory implementation failed to execute the operation.

findAllDirectories

List<Directory> findAllDirectories()

Will return a List<Directory> ordered by the order specified by the application.

Returns:

a List<Directory> or if there are no directories, an empty list (this should never happen)

findDirectoryById

Directory findDirectoryById(long directoryId)

Will return a Directory based on the given directoryId

Parameters:

directoryId - the id of the directory

Returns:

the directory or null if the directory is not found

updateDirectory

Directory updateDirectory(Directory directory)
                          throws OperationFailedException

Will update the Directory. The Directory must have at the bare minimum an Directory.getId(), Directory.getName(), Directory.getType() and Directory.getImplementationClass()}

Parameters:

directory - the directory to update

Returns:

the updated directory

Throws:

OperationFailedException - if the directory does not exist or the operation failed for any other reason.

setDirectoryPosition

void setDirectoryPosition(long directoryId,
                          int position)
                          throws OperationFailedException

Will place the directory with the given directoryId and the passed in position in the current list of directories configured for an application.

Parameters:

directoryId - the id of the directory

position - the position in the list of directories where you would like this one to be

Throws:

OperationFailedException - if the directory does not exist or the operation failed for any other reason

removeDirectory

boolean removeDirectory(long directoryId)
                        throws DirectoryCurrentlySynchronisingException,
                               OperationFailedException

Will remove a directory from the Application, this will also remove all associated entities (users/groups/memberships). TODO: We should discuss this

Parameters:

directoryId - the directory id of the Directory to remove.

Returns:

true if the directory and associated entities were removed, or false otherwise

Throws:

DirectoryCurrentlySynchronisingException - if the Directory is currently synchronising.

OperationFailedException - if the directory does not exist or the operation failed for any other reason

supportsNestedGroups

boolean supportsNestedGroups(long directoryId)
                             throws OperationFailedException

Returns true if the underlying directory implementation supports nested groups.

Parameters:

directoryId - ID of directory.

Returns:

true if the directory supports nested groups

Throws:

OperationFailedException - if the operation failed for any reason

isDirectorySynchronisable

boolean isDirectorySynchronisable(long directoryId)
                                  throws OperationFailedException

Returns true if the underlying directory implementation supports manual synchronisation of the directory's local cache.

Parameters:

directoryId - ID of directory.

Returns:

true if the directory supports synchronisation

Throws:

OperationFailedException - if the operation failed for any reason

synchroniseDirectory

void synchroniseDirectory(long directoryId)
                          throws OperationFailedException

Requests that this directory should update its cache by synchronising with the remote server. The synchronisation will occur asynchronously, i.e. this method returns immediately and the synchronization continues in the background.

If a synchronisation is currently in progress when this method is called, then this method does nothing.

Parameters:

directoryId - ID of directory.

Throws:

OperationFailedException - if the operation failed for any reason

synchroniseDirectory

void synchroniseDirectory(long directoryId,
                          boolean runInBackground)
                          throws OperationFailedException

Requests that this directory should update its cache by synchronising with the remote server.

If a synchronisation is currently in progress when this method is called, then this method does nothing if runInBackGround is true, otherwise it will throw OperationFailedException.

Parameters:

directoryId - ID of directory.

runInBackground - If True the synchronise will happen asynchronously.

Throws:

OperationFailedException - if the operation failed for any reason

isDirectorySynchronising

boolean isDirectorySynchronising(long directoryId)
                                 throws OperationFailedException

Returns true if the given Directory is currently synchronising.

Parameters:

directoryId - ID of directory.

Returns:

true if the given Directory is currently synchronising.

Throws:

OperationFailedException - if the operation failed for any reason

getDirectorySynchronisationInformation

DirectorySynchronisationInformation getDirectorySynchronisationInformation(long directoryId)
                                                                           throws OperationFailedException

Returns the synchronisation information for the directory. This includes the last sync start time and duration, and the current sync start time (if directory is currently synchronising).

Parameters:

directoryId - ID of directory

Returns:

a DirectorySynchronisationInformation object that contains the synchronisation information for the directory. null if the RemoteDirectory is not an instance of SynchronisableDirectory

Throws:

OperationFailedException - if the operation failed for any reason

setConnectionPoolProperties

void setConnectionPoolProperties(ConnectionPoolProperties poolProperties)

Stores the provided LDAP connection pool properties so they can be applied when the system next restarts.

Parameters:

poolProperties - the LDAP connection pool properties to be stored and applied on the next restart

See Also:

getStoredConnectionPoolProperties(), getSystemConnectionPoolProperties()

getStoredConnectionPoolProperties

ConnectionPoolProperties getStoredConnectionPoolProperties()

Retrieves the stored LDAP connection pool properties which will be applied when the system restarts.

Returns:

LdapPoolProperties the stored connection pool settings

See Also:

to retrieve the currently active settings

getSystemConnectionPoolProperties

ConnectionPoolProperties getSystemConnectionPoolProperties()

Retrieves the system LDAP connection pool properties (i.e. the currently active settings).

Returns:

LdapPoolProperties the system connection pool settings

See Also:

to retrieve the stored configuration which will be applied when the system next restarts