org.forgerock.opendj.server.core

Interface DataProvider

All Superinterfaces:

org.forgerock.opendj.ldap.RequestHandler<Operation>

All Known Implementing Classes:

AbstractDataProvider

public interface DataProvider
extends org.forgerock.opendj.ldap.RequestHandler<Operation>

An entry container which provides the content of one or more sub-trees.

A data provider can be:

• a simple data source such as a local back-end, a remote LDAP server or a local LDIF file.
• used to route operations. This is the case for load balancing and distribution.
• combine and transform data from underlying data providers. For example, DN mapping, attribute renaming, attribute value transformations, etc.

Data providers operate in two states:

• initialized
• accepting requests

Data providers are created in the initialized state. In this state a data provider has validated its configuration and registered support for off-line services such as export, import, backup, and restore if available.

A data provider transitions to the accepting requests state when the startDataProvider() method is invoked. In this state a data provider has acquired any remaining resources that it needs in order to be fully operational. This may include connections to underlying data providers. See the documentation for startDataProvider() for more information.

A data provider transitions back to the initialized state using the stopDataProvider() method. This occurs when the data provider is no longer needed in order process client requests, but may still be needed in order to perform off-line services such as import, export, backup, and restore.

If data provider is disabled or deleted from the server configuration or if the server is shutdown, then the finalizeDataProvider() method is invoked. This method should ensure that the data provider is stopped and no longer available for off-line services such as import, export, backup, and restore.

Method Summary

Modifier and Type	Method and Description
boolean	containsEntry(org.forgerock.opendj.ldap.DN dn) Indicates whether this data provider contains the specified entry.
void	deregisterEventListener(DataProviderEventListener listener) Deregisters an event listener from this data provider.
void	finalizeDataProvider() Performs any necessary work to finalize this data provider.
Set<org.forgerock.opendj.ldap.DN>	getBaseDNs() Returns an unmodifiable set containing the base DNs of the sub-trees which this data provider contains.
org.forgerock.opendj.ldap.Entry	getEntry(org.forgerock.opendj.ldap.DN dn) Retrieves the specified entry from this data provider.
DataProviderStatus	getStatus(org.forgerock.opendj.ldap.DN baseDN) Returns the current status of the provided base DN in this data provider.
Set<String>	getSupportedControls(org.forgerock.opendj.ldap.DN baseDN) Returns an unmodifiable set containing the OIDs of the controls that may be supported by the provided base DN in this data provider.
Set<String>	getSupportedFeatures(org.forgerock.opendj.ldap.DN baseDN) Returns an unmodifiable set containing the OIDs of the features that may be supported by the provided base DN in this data provider.
void	registerEventListener(DataProviderEventListener listener) Registers an event listener with this data provider.
void	startDataProvider() Starts this data provider so that it is ready to process client requests.
void	stopDataProvider() Performs any necessary work to stop this data provider.
boolean	supportsChangeNotification(org.forgerock.opendj.ldap.DN baseDN) Indicates whether the provided base DN in this data provider supports change notification.

Methods inherited from interface org.forgerock.opendj.ldap.RequestHandler

handleAdd, handleBind, handleCompare, handleDelete, handleExtendedRequest, handleModify, handleModifyDN, handleSearch

Method Detail

containsEntry

boolean containsEntry(org.forgerock.opendj.ldap.DN dn)
               throws org.forgerock.opendj.ldap.LdapException

Indicates whether this data provider contains the specified entry.

Parameters:

dn - The DN of the entry.

Returns:

true if this data provider contains the specified entry, or false if it does not.

Throws:

org.forgerock.opendj.ldap.LdapException - If a problem occurs while trying to make the determination, or if dn is not a DN equal to or subordinate to one of the base DNs managed by this data provider.

deregisterEventListener

void deregisterEventListener(DataProviderEventListener listener)

Deregisters an event listener from this data provider.

Parameters:

listener - The event listener.

finalizeDataProvider

void finalizeDataProvider()

Performs any necessary work to finalize this data provider. This may include closing any connections to underlying data providers, databases, and deregistering any listeners, etc.

This method may be called during the Directory Server shutdown process or if a data provider is disabled with the server online. It must not return until this data provider is finalized.

Implementations should assume that this data provider has already been stopped using stopDataProvider().

Implementations must deregister any listeners such as those required for performing import, export, backup, and restore.

Implementations must not throw any exceptions. If any problems are encountered, then they may be logged but the closure should progress as completely as possible.

getBaseDNs

Set<org.forgerock.opendj.ldap.DN> getBaseDNs()

Returns an unmodifiable set containing the base DNs of the sub-trees which this data provider contains.

Returns:

An unmodifiable set containing the base DNs of the sub-trees which this data provider contains.

getEntry

org.forgerock.opendj.ldap.Entry getEntry(org.forgerock.opendj.ldap.DN dn)
                                  throws org.forgerock.opendj.ldap.LdapException

Retrieves the specified entry from this data provider.

Parameters:

dn - The DN of the entry.

Returns:

The requested entry, or null if this data provider does not contain the specified entry.

Throws:

org.forgerock.opendj.ldap.LdapException - If a problem occurs while trying to retrieve the entry, or if dn is not a DN equal to or subordinate to one of the base DNs managed by this data provider.

getStatus

DataProviderStatus getStatus(org.forgerock.opendj.ldap.DN baseDN)
                      throws org.forgerock.opendj.ldap.LdapException

Returns the current status of the provided base DN in this data provider.

Parameters:

baseDN - The base DN in this data provider.

Returns:

The current status of the provided base DN in this data provider.

Throws:

org.forgerock.opendj.ldap.LdapException - If baseDN is not one of the base DNs managed by this data provider.

getSupportedControls

Set<String> getSupportedControls(org.forgerock.opendj.ldap.DN baseDN)
                          throws org.forgerock.opendj.ldap.LdapException

Returns an unmodifiable set containing the OIDs of the controls that may be supported by the provided base DN in this data provider.

Parameters:

baseDN - The base DN in this data provider.

Returns:

An unmodifiable set containing the OIDs of the controls that may be supported by the provided base DN in this data provider.

Throws:

org.forgerock.opendj.ldap.LdapException - If baseDN is not one of the base DNs managed by this data provider.

getSupportedFeatures

Set<String> getSupportedFeatures(org.forgerock.opendj.ldap.DN baseDN)
                          throws org.forgerock.opendj.ldap.LdapException

Returns an unmodifiable set containing the OIDs of the features that may be supported by the provided base DN in this data provider.

Parameters:

baseDN - The base DN in this data provider.

Returns:

An unmodifiable set containing the OIDs of the features that may be supported by the provided base DN in this data provider.

Throws:

org.forgerock.opendj.ldap.LdapException - If baseDN is not one of the base DNs managed by this data provider.

registerEventListener

void registerEventListener(DataProviderEventListener listener)

Registers an event listener with this data provider.

Parameters:

listener - The event listener.

startDataProvider

void startDataProvider()

Starts this data provider so that it is ready to process client requests. This method is called immediately before the first data provider connection is opened.

Implementations must acquire any remaining resources in order to make this data provider fully operational. This may include any of the following:

• connections to other data providers
• connections to remote databases
• connections to remote servers
• opening local databases and files
• pre-loading databases.

Implementations must perform all required work synchronously such that, on return, this data provider is fully operational.

stopDataProvider

void stopDataProvider()

Performs any necessary work to stop this data provider. This includes closing any connections to underlying data providers, databases, etc.

This method is called immediately after the last data provider connection is closed. It must not return until this data provider is stopped.

Implementations must release all resources acquired when this data provider was started. This includes:

• connections to other data providers
• connections to remote databases
• connections to remote servers
• closing local databases and files.

Implementations must not deregister this data provider or any associated listeners such as those required for performing import, export, backup, and restore.

Implementations must not throw any exceptions. If any problems are encountered, then they may be logged but the shutdown should progress as completely as possible.

supportsChangeNotification

boolean supportsChangeNotification(org.forgerock.opendj.ldap.DN baseDN)
                            throws org.forgerock.opendj.ldap.LdapException

Indicates whether the provided base DN in this data provider supports change notification.

Parameters:

baseDN - The base DN in this data provider.

Returns:

true if the provided base DN in this data provider supports change notification.

Throws:

org.forgerock.opendj.ldap.LdapException - If baseDN is not one of the base DNs managed by this data provider.