Package 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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.