Package com.unboundid.util

Class SubtreeDeleter

java.lang.Object
com.unboundid.util.SubtreeDeleter
@Mutable @ThreadSafety(level=NOT_THREADSAFE) public final class SubtreeDeleter extends Object
This class provides a utility that can delete all entries below a specified base DN (including the base entry itself by default, although it can be preserved if desired) in an LDAP directory server. It accomplishes this through a combination of search and delete operations. Ideally, it will first perform a search to find all entries below the target base DN, but in some cases, it may be necessary to intertwine search and delete operations if it is not possible to retrieve all entries in the target subtree in advance.

The subtree deleter can optionally take advantage of a number of server features to aid in processing, but does not require them. Some of these features include:
  • Set Subtree Accessibility Extended Operation -- A proprietary extended operation supported by the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server products. This operation can restrict access to a specified subtree to all but a specified user. If this is to be used, then the "Who Am I?" extended operation will first be used to identify the user that is authenticated on the provided connection, and then the set subtree accessibility extended operation will be used to make the target subtree hidden and read-only for all users except the user identified by the "Who Am I?" operation. As far as all other clients are concerned, this will make the target subtree immediately disappear. The subtree deleter will then be able to search for the entries to delete, and then delete those entries, without exposing other clients to its in-progress state.

    The set subtree accessibility extended operation will not automatically be used. If the setUseSetSubtreeAccessibilityOperationIfAvailable(boolean) method is called with a value of true, then this extended operation will be used if the server root DSE advertises support for both this operation and the LDAP "Who Am I?" extended operation.

  • Simple Paged Results Request Control -- A standard request control that is supported by several types of directory servers. This control allows a search to be broken up into pages to limit the number of entries that are returned in any single operation (which can help an authorized client circumvent search size limit restrictions). It can also help ensure that if the server can return entries faster than the client can consume them, it will not result in a large backlog on the server.

    The simple paged results request control will be used by default if the server root DSE advertises support for it, with a default page size of 100 entries.

  • Manage DSA IT Request Control -- A standard request control that is supported by several types of directory servers. This control indicates that any referral entries (that is, entries that contain the "referral" object class and a "ref" attribute) should be treated as regular entries rather than triggering a referral result or a search result reference. The subtree deleter will not make any attempt to follow referrals, and if any referral or search result reference results are returned during processing, then it may not be possible to completely remove all entries in the target subtree.

    The manage DSA IT request control will be used by default if the server root DSE advertises support for it.

  • Permit Unindexed Search Request Control -- A proprietary request control supported by the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server products. This control indicates that the client wishes to process the search even if it is unindexed.

    The permit unindexed search request control will not automatically be used. It may not needed if the requester has the unindexed-search privilege, and the permit unindexed search request control requires that the caller have either the unindexed-search or unindexed-search-with-control privilege. If the setUsePermitUnindexedSearchControlIfAvailable(boolean) method is called with a value of true, then this control will be used if the server root DSE advertises support for it.

  • LDAP Subentries Request Control -- A standard request control that is supported by several types of directory servers. It allows the client to request a search that retrieves entries with the "ldapSubentry" object class, which are normally excluded from search results. Note that because of the nature of this control, if it is to be used, then two separate sets of searches will be used: one that retrieves only LDAP subentries, and a second that retrieves other types of entries.

    The LDAP subentries request control will be used by default if the server root DSE advertises support for it.

  • Return Conflict Entries Request Control -- A proprietary request control that is supported by the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server products. This control indicates that the server should return replication conflict entries, which are normally excluded from search results.

    The return conflict entries request control will be used by default if the server root DSE advertises support for it.

  • Soft-Deleted Entry Access Request Control -- A proprietary request control that is supported by the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server products. This control indicates that the server should return soft-deleted entries, which are normally excluded from search results.

    The soft-deleted entry access request control will be used by default if the server root DSE advertises support for it.

  • Hard Delete Request Control -- A proprietary request control that is supported by the Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 Directory Server products. This control indicates that the server should process a delete operation as a hard delete, even if a soft-delete policy would have otherwise converted it into a soft delete. A subtree cannot be deleted if it contains soft-deleted entries, so this should be used if the server is configured with such a soft-delete policy.

    The hard delete request control will be used by default if the server root DSE advertises support for it.

  • Constructor Details

    • SubtreeDeleter

      public SubtreeDeleter()
      Creates a new instance of this subtree deleter with the default settings.

  • Method Details

    • deleteBaseEntry

      public boolean deleteBaseEntry()
      Indicates whether the base entry itself should be deleted along with all of its subordinates. This method returns true by default.
      Returns:
      true if the base entry should be deleted in addition to its subordinates, or false if the base entry should not be deleted but all of its subordinates should be.

    • setDeleteBaseEntry

      public void setDeleteBaseEntry(boolean deleteBaseEntry)
      Specifies whether the base entry itself should be deleted along with all of its subordinates.
      Parameters:
      deleteBaseEntry - true to indicate that the base entry should be deleted in addition to its subordinates, or false if only the subordinates of the base entry should be removed.

    • useSetSubtreeAccessibilityOperationIfAvailable

      public boolean useSetSubtreeAccessibilityOperationIfAvailable()
      Indicates whether to use the SetSubtreeAccessibilityExtendedRequest to make the target subtree hidden before starting to search for entries to delete if the server root DSE advertises support for both that extended request and the "Who Am I?" extended request. In servers that support it, this extended operation can make the target subtree hidden and read-only to clients other than those authenticated as the user that issued the set subtree accessibility request.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports both the set subtree accessibility extended operation and the "Who Am I?" extended operation.
      Returns:
      true if the set subtree accessibility extended operation should be used to make the target subtree hidden and read-only before attempting to search for entries to delete if the server root DSE advertises support for it, or false if the operation should not be used.

    • setUseSetSubtreeAccessibilityOperationIfAvailable

      public void setUseSetSubtreeAccessibilityOperationIfAvailable(boolean useSetSubtreeAccessibilityOperationIfAvailable)
      Specifies whether to use the SetSubtreeAccessibilityExtendedRequest to make the target subtree hidden before starting to search for entries to delete if the server root DSE advertises support for both that extended request and the "Who Am I?" extended request. In servers that support it, this extended operation can make the target subtree hidden and read-only to clients other than those authenticated as the user that issued the set subtree accessibility request.
      Parameters:
      useSetSubtreeAccessibilityOperationIfAvailable - true to indicate that the set subtree accessibility extended operation should be used to make the target subtree hidden and read-only before starting to search for entries to delete, or false if not. This value will be ignored if the server root DSE does not advertise support for both the set subtree accessibility extended operation and the "Who Am I?" extended operation.

    • useSimplePagedResultsControlIfAvailable

      public boolean useSimplePagedResultsControlIfAvailable()
      Indicates whether to use the SimplePagedResultsControl when searching for entries to delete if the server advertises support for it. Using this control can help avoid problems from running into the search size limit, and can also prevent the server from trying to return entries faster than the client can consume them.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the simple paged results control.
      Returns:
      true if the simple paged results control should be used when searching for entries to delete if the server root DSE advertises support for it, or false if the control should not be used.

    • setUseSimplePagedResultsControlIfAvailable

      public void setUseSimplePagedResultsControlIfAvailable(boolean useSimplePagedResultsControlIfAvailable)
      Specifies whether to use the SimplePagedResultsControl when searching for entries to delete if the server advertises support for it. Using this control can help avoid problems from running into the search size limit, and can also prevent the server from trying to return entries faster than the client can consume them.
      Parameters:
      useSimplePagedResultsControlIfAvailable - true to indicate that the simple paged results control should be used when searching for entries to delete, or false if not. This value will be ignored if the server root DSE does not advertise support for the simple paged results control.

    • getSimplePagedResultsPageSize

      public int getSimplePagedResultsPageSize()
      Retrieves the maximum number of entries that should be returned in each page of results when using the simple paged results control. This value will only be used if useSimplePagedResultsControlIfAvailable() returns true and the server root DSE indicates that it supports the simple paged results control.

      This method returns 100 by default. Its value will be ignored if the server root DSE does not indicate that it supports the simple paged results control.
      Returns:
      The maximum number of entries that should be returned in each page of results when using the simple paged results control.

    • setSimplePagedResultsPageSize

      public void setSimplePagedResultsPageSize(int simplePagedResultsPageSize)
      Specifies the maximum number of entries that should be returned in each page of results when using the simple paged results control. This value will only be used if useSimplePagedResultsControlIfAvailable() returns true and the server root DSE indicates that it supports the simple paged results control.
      Parameters:
      simplePagedResultsPageSize - The maximum number of entries that should be returned in each page of results when using the simple paged results control. The value must be greater than or equal to one.

    • useManageDSAITControlIfAvailable

      public boolean useManageDSAITControlIfAvailable()
      Indicates whether to include the ManageDsaITRequestControl in search and delete requests if the server root DSE advertises support for it. The manage DSA IT request control tells the server that it should return referral entries as regular entries rather than returning them as search result references when processing a search operation, or returning a referral result when attempting a delete. If any referrals are encountered during processing and this control is not used, then it may not be possible to completely delete the entire subtree.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the manage DSA IT request control.
      Returns:
      true if the manage DSA IT request control should be included in search and delete requests if the server root DSE advertises support for it, or false if not.

    • setUseManageDSAITControlIfAvailable

      public void setUseManageDSAITControlIfAvailable(boolean useManageDSAITControlIfAvailable)
      Specifies whether to include the ManageDsaITRequestControl in search and delete requests if the server root DSE advertises support for it. The manage DSA IT request control tells the server that it should return referral entries as regular entries rather than returning them as search result references when processing a search operation, or returning a referral result when attempting a delete. If any referrals are encountered during processing and this control is not used, then it may not be possible to completely delete the entire subtree.
      Parameters:
      useManageDSAITControlIfAvailable - true to indicate that the manage DSA IT request control should be included in search and delete requests, or false if not. This value will be ignored if the server root DSE does not advertise support for the manage DSA IT request control.

    • usePermitUnindexedSearchControlIfAvailable

      public boolean usePermitUnindexedSearchControlIfAvailable()
      Indicates whether to include the PermitUnindexedSearchRequestControl in search requests used to identify the entries to be deleted if the server root DSE advertises support for it. The permit unindexed search request control may allow appropriately authorized clients to explicitly indicate that the server should process an unindexed search that would normally be rejected.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the permit unindexed search request control.
      Returns:
      true if search requests should include the permit unindexed search request control if the server root DSE advertises support for it, or false if not.

    • setUsePermitUnindexedSearchControlIfAvailable

      public void setUsePermitUnindexedSearchControlIfAvailable(boolean usePermitUnindexedSearchControlIfAvailable)
      Specifies whether to include the PermitUnindexedSearchRequestControl in search request used to identify the entries to be deleted if the server root DSE advertises support for it. The permit unindexed search request control may allow appropriately authorized clients to explicitly indicate that the server should process an unindexed search that would normally be rejected.
      Parameters:
      usePermitUnindexedSearchControlIfAvailable - true to indicate that the permit unindexed search request control should be included in search requests, or false if not. This value will be ignored if the server root DSE does not advertise support for the permit unindexed search request control.

    • useSubentriesControlIfAvailable

      public boolean useSubentriesControlIfAvailable()
      Indicates whether to use the DraftLDUPSubentriesRequestControl when searching for entries to delete if the server root DSE advertises support for it. The subentries request control allows LDAP subentries to be included in search results. These entries are normally excluded from search results.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the subentries request control.
      Returns:
      true if the subentries request control should be used to retrieve LDAP subentries if the server root DSE advertises support for it, or false if not.

    • setUseSubentriesControlIfAvailable

      public void setUseSubentriesControlIfAvailable(boolean useSubentriesControlIfAvailable)
      Specifies whether to use the DraftLDUPSubentriesRequestControl when searching for entries to delete if the server root DSE advertises support for it. The subentries request control allows LDAP subentries to be included in search results. These entries are normally excluded from search results.
      Parameters:
      useSubentriesControlIfAvailable - [@code true} to indicate that the subentries request control should be used to retrieve LDAP subentries, or false if not. This value will be ignored if the server root DSE does not advertise support for the subentries request control.

    • useReturnConflictEntriesRequestControlIfAvailable

      public boolean useReturnConflictEntriesRequestControlIfAvailable()
      Indicates whether to use the ReturnConflictEntriesRequestControl when searching for entries to delete if the server root DSE advertises support for it. The return conflict entries request control allows replication conflict entries to be included in search results. These entries are normally excluded from search results.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the return conflict entries request control.
      Returns:
      true if the return conflict entries request control should be used to retrieve replication conflict entries if the server root DSE advertises support for it, or false if not.

    • setUseReturnConflictEntriesRequestControlIfAvailable

      public void setUseReturnConflictEntriesRequestControlIfAvailable(boolean useReturnConflictEntriesRequestControlIfAvailable)
      Specifies whether to use the ReturnConflictEntriesRequestControl when searching for entries to delete if the server root DSE advertises support for it. The return conflict entries request control allows replication conflict entries to be included in search results. These entries are normally excluded from search results.
      Parameters:
      useReturnConflictEntriesRequestControlIfAvailable - true to indicate that the return conflict entries request control should be used to retrieve replication conflict entries, or false if not. This value will be ignored if the server root DSE does not advertise support for the return conflict entries request control.

    • useSoftDeletedEntryAccessControlIfAvailable

      public boolean useSoftDeletedEntryAccessControlIfAvailable()
      Indicates whether to use the SoftDeletedEntryAccessRequestControl when searching for entries to delete if the server root DSE advertises support for it. The soft-deleted entry access request control allows soft-deleted entries to be included in search results. These entries are normally excluded from search results.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the soft-deleted entry access request control.
      Returns:
      true if the soft-deleted entry access request control should be used to retrieve soft-deleted entries if the server root DSE advertises support for it, or false if not.

    • setUseSoftDeletedEntryAccessControlIfAvailable

      public void setUseSoftDeletedEntryAccessControlIfAvailable(boolean useSoftDeletedEntryAccessControlIfAvailable)
      Specifies whether to use the SoftDeletedEntryAccessRequestControl when searching for entries to delete if the server root DSE advertises support for it. The soft-deleted entry access request control allows soft-deleted entries to be included in search results. These entries are normally excluded from search results.
      Parameters:
      useSoftDeletedEntryAccessControlIfAvailable - true to indicate that the soft-deleted entry access request control should be used to retrieve soft-deleted entries, or false if not. This value will be ignored if the server root DSE does not advertise support for the soft-deleted entry access request control.

    • useHardDeleteControlIfAvailable

      public boolean useHardDeleteControlIfAvailable()
      Indicates whether to include the HardDeleteRequestControl in delete requests if the server root DSE advertises support for it. The hard delete request control indicates that the server should treat a delete operation as a hard delete even if it would have normally been processed as a soft delete because it matches the criteria in a configured soft delete policy.

      This method returns true by default. Its value will be ignored if the server root DSE does not indicate that it supports the hard delete request control.
      Returns:
      true if the hard delete request control should be included in delete requests if the server root DSE advertises support for it, or false if not.

    • setUseHardDeleteControlIfAvailable

      public void setUseHardDeleteControlIfAvailable(boolean useHardDeleteControlIfAvailable)
      Specifies whether to include the HardDeleteRequestControl in delete requests if the server root DSE advertises support for it. The hard delete request control indicates that the server should treat a delete operation as a hard delete even if it would have normally been processed as a soft delete because it matches the criteria in a configured soft delete policy.
      Parameters:
      useHardDeleteControlIfAvailable - true to indicate that the hard delete request control should be included in delete requests, or false if not. This value will be ignored if the server root DSE does not advertise support for the hard delete request control.

    • getAdditionalSearchControls

      @NotNull public List<Control> getAdditionalSearchControls()
      Retrieves an unmodifiable list of additional controls that should be included in search requests used to identify entries to delete.

      This method returns an empty list by default.
      Returns:
      An unmodifiable list of additional controls that should be included in search requests used to identify entries to delete.

    • setAdditionalSearchControls

      public void setAdditionalSearchControls(@NotNull Control... additionalSearchControls)
      Specifies a list of additional controls that should be included in search requests used to identify entries to delete.
      Parameters:
      additionalSearchControls - A list of additional controls that should be included in search requests used to identify entries to delete. This must not be null but may be empty.

    • setAdditionalSearchControls

      public void setAdditionalSearchControls(@NotNull List<Control> additionalSearchControls)
      Specifies a list of additional controls that should be included in search requests used to identify entries to delete.
      Parameters:
      additionalSearchControls - A list of additional controls that should be included in search requests used to identify entries to delete. This must not be null but may be empty.

    • getAdditionalDeleteControls

      @NotNull public List<Control> getAdditionalDeleteControls()
      Retrieves an unmodifiable list of additional controls that should be included in delete requests.

      This method returns an empty list by default.
      Returns:
      An unmodifiable list of additional controls that should be included in delete requests.

    • setAdditionalDeleteControls

      public void setAdditionalDeleteControls(@NotNull Control... additionalDeleteControls)
      Specifies a list of additional controls that should be included in delete requests.
      Parameters:
      additionalDeleteControls - A list of additional controls that should be included in delete requests. This must not be null but may be empty.

    • setAdditionalDeleteControls

      public void setAdditionalDeleteControls(@NotNull List<Control> additionalDeleteControls)
      Specifies a list of additional controls that should be included in delete requests.
      Parameters:
      additionalDeleteControls - A list of additional controls that should be included in delete requests. This must not be null but may be empty.

    • getSearchRequestSizeLimit

      public int getSearchRequestSizeLimit()
      Retrieves the size limit that should be used in each search request to specify the maximum number of entries to return in response to that request. If a search request matches more than this number of entries, then the server may return a subset of the results and a search result done message with a result code of ResultCode.SIZE_LIMIT_EXCEEDED.

      This method returns a value of zero by default, which indicates that the client does not want to impose any limit on the number of entries that may be returned in response to any single search operation (although the server may still impose a limit).
      Returns:
      The size limit that should be used in each search request to specify the maximum number of entries to return in response to that request, or zero to indicate that the client does not want to impose any size limit.

    • setSearchRequestSizeLimit

      public void setSearchRequestSizeLimit(int searchRequestSizeLimit)
      Specifies the size limit that should be used in each search request to specify the maximum number of entries to return in response to that request. If a search request matches more than this number of entries, then the server may return a subset of the results and a search result done message with a result code of ResultCode.SIZE_LIMIT_EXCEEDED. A value that is less than or equal to zero indicates that the client does not want to impose any limit on the number of entries that may be returned in response to any single search operation (although the server may still impose a limit).
      Parameters:
      searchRequestSizeLimit - The size limit that should be used in each search request to specify the maximum number of entries to return in response to that request. A value that is less than or equal to zero indicates that the client does not want to impose any size limit.

    • getDeleteRateLimiter

      @Nullable public FixedRateBarrier getDeleteRateLimiter()
      Retrieves the fixed-rate barrier that may be used to impose a rate limit on delete operations, if defined.

      This method returns null by default, to indicate that no delete rate limit will be imposed.
      Returns:
      The fixed-rate barrier that may be used to impose a rate limit on delete operations, or null if no rate limit should be imposed.

    • setDeleteRateLimiter

      public void setDeleteRateLimiter(@Nullable FixedRateBarrier deleteRateLimiter)
      Provides a fixed-rate barrier that may be used to impose a rate limit on delete operations.
      Parameters:
      deleteRateLimiter - A fixed-rate barrier that may be used to impose a rate limit on delete operations. It may be null if no delete rate limit should be imposed.

    • delete

      @NotNull public SubtreeDeleterResult delete(@NotNull LDAPInterface connection, @NotNull String baseDN) throws LDAPException
      Attempts to delete the specified subtree using the current settings.
      Parameters:
      connection - The LDAPInterface instance to use to communicate with the directory server. While this may be an individual LDAPConnection, it may be better as a connection pool with automatic retry enabled so that it's more likely to succeed in the event that a connection becomes invalid or an operation experiences a transient failure. It must not be null.
      baseDN - The base DN for the subtree to delete. It must not be null.
      Returns:
      An object with information about the results of the subtree delete processing.
      Throws:
      LDAPException - If the provided base DN cannot be parsed as a valid DN.

    • delete

      @NotNull public SubtreeDeleterResult delete(@NotNull LDAPInterface connection, @NotNull DN baseDN)
      Attempts to delete the specified subtree using the current settings.
      Parameters:
      connection - The LDAPInterface instance to use to communicate with the directory server. While this may be an individual LDAPConnection, it may be better as a connection pool with automatic retry enabled so that it's more likely to succeed in the event that a connection becomes invalid or an operation experiences a transient failure. It must not be null.
      baseDN - The base DN for the subtree to delete. It must not be null.
      Returns:
      An object with information about the results of the subtree delete processing.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of this subtree deleter.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this subtree deleter.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this subtree deleter to the provided buffer.
      Parameters:
      buffer - The buffer to which the string representation should be appended.