com.adobe.idp.um.spi.directoryservices
Interface DirectoryPrincipalProvider

All Known Subinterfaces:

DirectoryGroupProvider, DirectoryUserProvider

public interface DirectoryPrincipalProvider

The DirectoryPrincipalProvider interface is the base interface for user and group provider interfaces. This interface defines methods for retrieving user records from a repository of a specified domain. This interface also defines constant values that represent exception types for reporting error information to Adobe User Management.

It is expected that retrieving a large number of records at the same time is undesirable. This interface defines a mechanism for retrieving records by using sequential calls, each call retrieving a specific number of records until all records are retrieved. Adobe User Management and the implementing classes must communicate to ensure that all available records are retrieved.

Information about the repository and the connection parameters can be preconfigured on Adobe User Management. Implementations of this interface can access that information to retrieve the records.

See Also:

DirectoryGroupProvider, DirectoryUserProvider

Field Summary

static int	E_DIRSERVICES_COLLIDING_PRINCIPAL_SPEC A constant that indicates multiple principals use the same identifier.
static int	E_DIRSERVICES_CONFIGURATION_ERROR A constant that indicates the provided DirectoryProviderConfig object was rejected.
static int	E_DIRSERVICES_PROVIDER_DATA_ERROR A constant that indicates a problem with the retrieved records.
static int	E_DIRSERVICES_PROVIDER_UNKNOWN_ERROR A constant that indicates an unexpected error occurred.

Method Summary

DSPrincipalCollection	getPrincipals(DirectoryProviderConfig config, java.lang.Object state) Retrieves user records from a repository according to the provided parameters.
boolean	testConfiguration(DirectoryProviderConfig config) Performs a simple test to determine whether the configuration settings associated with the directory service provider are correct.

Field Detail

E_DIRSERVICES_CONFIGURATION_ERROR

static final int E_DIRSERVICES_CONFIGURATION_ERROR

A constant that indicates the provided DirectoryProviderConfig object was rejected.

See Also:

Constant Field Values

E_DIRSERVICES_COLLIDING_PRINCIPAL_SPEC

static final int E_DIRSERVICES_COLLIDING_PRINCIPAL_SPEC

A constant that indicates multiple principals use the same identifier.

See Also:

Constant Field Values

E_DIRSERVICES_PROVIDER_DATA_ERROR

static final int E_DIRSERVICES_PROVIDER_DATA_ERROR

A constant that indicates a problem with the retrieved records.

See Also:

Constant Field Values

E_DIRSERVICES_PROVIDER_UNKNOWN_ERROR

static final int E_DIRSERVICES_PROVIDER_UNKNOWN_ERROR

A constant that indicates an unexpected error occurred.

See Also:

Constant Field Values

Method Detail

getPrincipals

DSPrincipalCollection getPrincipals(DirectoryProviderConfig config,
                                    java.lang.Object state)
                                    throws IDPException

Retrieves user records from a repository according to the provided parameters. This method retrieves a predetermined maximum number of records for each call. Adobe User Management calls this method several times until all records are retrieved.

This method defines parameters for communicating the state of the record retrieval process, of which the current call is a part:

• Adobe User Management determines whether the current call is an initial call or whether it is related to a previous call.
• The implementation indicates to Adobe User Management whether there are more records to retrieve.

The implementation of this method will enumerate results as well as return state information. To indicate that the call has been successful, the implementation should instead return null.

The information originates from the configuration settings on Adobe User Management. Adobe User Management provides the DirectoryProviderConfig object when it calls the implementations of the DirectoryUserProvider and DirectoryGroupProvider interfaces.

Parameters:

config - A DirectoryProviderConfig object that contains information about the records to retrieve, such as the domain and other information specific to the implementation.

state - An Object instance that contains either null or the state returned from the previous call to this method:

• state contains null if the call is the initial call to this method.
• state contains the state from the previous call if the current call is one of a series.

The information that describes the state depends on your implementation.

In subsequent calls, Adobe User Management includes the parameter with the same value that the implementation previously returned. Therefore, the parameter can be used to specify any information that the implementation requires to track the progress; for example, the identification of the last record retrieved.

Returns:

A DSPrincipalCollection object that contains either the retrieved records and the state, or null:

• The method returns a DSPrincipalCollection object if there were records to return.
• The method returns null if there were no records to return.

Throws:

IDPException - if the method provides unexpected results.

The exception can include one of the following constants as the message:

• DirectoryPrincipalProvider.E_DIRSERVICES_CONFIGURATION_ERROR
• DirectoryPrincipalProvider.E_DIRSERVICES_COLLIDING_PRINCIPAL_SPEC
• DirectoryPrincipalProvider.E_DIRSERVICES_PROVIDER_DATA_ERROR
• DirectoryPrincipalProvider.E_DIRSERVICES_PROVIDER_UNKNOWN_ERROR

testConfiguration

boolean testConfiguration(DirectoryProviderConfig config)

Performs a simple test to determine whether the configuration settings associated with the directory service provider are correct.

Parameters:

config - A DirectoryProviderConfig object that contains the configuration to test.

Returns:

true if the results of the test are as expected, false if unexpected results occur.