Package com.unboundid.ldap.sdk.unboundidds.tools

Class LDAPDiff

  • @ThreadSafety(level=NOT_THREADSAFE)
public final class LDAPDiff
extends MultiServerLDAPCommandLineTool
    This class provides a tool that can be used to compare the contents of two LDAPv3 servers and report the differences in an LDIF file that can be used to update the source server to match the target. It should work with any pair of LDAPv3 servers, including servers of different types.
    NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

    This tool can be used to determine whether two LDAP replicas are in sync. It can also account for replication delay by checking differing entries multiple times.

    At a minimum, the user must provide information needed to connect and authenticate to the two servers to compare, as well as the base DN below authenticate to the two servers to compare, as well as the base DN below which to search (note that the empty base DN is not supported). The user can optionally also specify a filter used to identify which entries should be compared.

    This tool tries to compare the contents of both servers as quickly as possible while also maintaining a low memory overhead and eliminating false positives that result from entries that are temporarily out of sync as a result of replication latencies. It does this using the following approach:
    • Retrieve the DNs from each server in parallel. For servers that advertise support for the StreamDirectoryValuesExtendedRequest, then that operation will be used to retrieve the DNs. Otherwise, a search will be used with the configured base DN, scope, and filter to retrieve all matching entries (without any attributes).
    • For up to a configurable number of passes:
      1. Use a thread pool to iterate through all of the identified entry DNs, fetching and comparing each entry from both servers. By default, multiple threads will be used to perform the comparison as fast as possible, but this can be configured as needed to adjust the performance impact on the directory servers.
      2. If the version of the entry retrieved from each server is the same, then it is considered in sync and will not be compared again. If the entry differs between the source and target servers, and if there are no more passes to complete, then the differences will be computed and written in LDIF form to an output file.
      3. If any differing entries were identified, and if there are more passes remaining, then the tool will wait for a specified length of time before re-retrieving and re-comparing each of the entries that differed in the last pass.
    Note that even though the tool operates in parallel, it ensures that the differences are written to the output file in an appropriate order to ensure that they can be replayed. The tool keeps the adds, modifies, and deletes separate during processing and then joins them at the end in an appropriate order (with deletes in reverse order to ensure that children are removed before parents, followed by modifies, and finally adds). Intermediate files are used during processing to hold the add and modify records to minimize memory consumption.

    Note that the accounts used to run this tool must be sufficiently privileged to perform the necessary processing, including being able to access all of the appropriate entries (and all relevant attributes in those entries) in each server.

    • Constructor Detail

      • LDAPDiff

        public LDAPDiff​(@Nullable
                java.io.OutputStream out,
                @Nullable
                java.io.OutputStream err)
        Creates a new instance of this tool with the provided information.
        Parameters:
        out - The output stream to use for standard output. It may be null if standard output should be suppressed.
        err - The output stream to use for standard error. It may be null if standard error should be suppressed.

    • Method Detail

      • main

        public static void main​(@NotNull
                        java.lang.String... args)
        Invokes this tool using the provided set of command-line arguments.
        Parameters:
        args - The command-line arguments provided to this program. It must not be null or empty.

      • main

        @NotNull
public static ResultCode main​(@Nullable
                              java.io.OutputStream out,
                              @Nullable
                              java.io.OutputStream err,
                              @NotNull
                              java.lang.String... args)
        Invokes this tool using the provided set of command-line arguments.
        Parameters:
        out - The output stream to use for standard output. It may be null if standard output should be suppressed.
        err - The output stream to use for standard error. It may be null if standard error should be suppressed.
        args - The command-line arguments provided to this program. It must not be null or empty.
        Returns:
        A result code that indicates the result of tool processing. A result code of ResultCode.SUCCESS indicates that all processing completed successfully and no differences were identified. A result code of ResultCode.COMPARE_FALSE indicates that all processing completed successfully but that one or more differences were identified between the source and target servers. Any other result code indicates that an error occurred during processing.

      • getToolName

        @NotNull
public java.lang.String getToolName()
        Retrieves the name of this tool. It should be the name of the command used to invoke this tool.
        Specified by:
        getToolName in class CommandLineTool
        Returns:
        The name for this tool.

      • getAdditionalDescriptionParagraphs

        @NotNull
public java.util.List<java.lang.String> getAdditionalDescriptionParagraphs()
        Retrieves additional paragraphs that should be included in the description for this tool. If the tool description should include multiple paragraphs, then the CommandLineTool.getToolDescription() method should return the text of the first paragraph, and each item in the list returned by this method should be the text for each subsequent paragraph. If the tool description should only have a single paragraph, then this method may return null or an empty list.
        Overrides:
        getAdditionalDescriptionParagraphs in class CommandLineTool
        Returns:
        Additional paragraphs that should be included in the description for this tool, or null or an empty list if only a single description paragraph (whose text is returned by the getToolDescription method) is needed.

      • getMaxTrailingArguments

        public int getMaxTrailingArguments()
        Retrieves the maximum number of unnamed trailing arguments that may be provided for this tool. If a tool supports trailing arguments, then it must override this method to return a nonzero value, and must also override the CommandLineTool.getTrailingArgumentsPlaceholder() method to return a non-null value.
        Overrides:
        getMaxTrailingArguments in class CommandLineTool
        Returns:
        The maximum number of unnamed trailing arguments that may be provided for this tool. A value of zero indicates that trailing arguments are not allowed. A negative value indicates that there should be no limit on the number of trailing arguments.

      • getTrailingArgumentsPlaceholder

        @NotNull
public java.lang.String getTrailingArgumentsPlaceholder()
        Retrieves a placeholder string that should be used for trailing arguments in the usage information for this tool.
        Overrides:
        getTrailingArgumentsPlaceholder in class CommandLineTool
        Returns:
        A placeholder string that should be used for trailing arguments in the usage information for this tool, or null if trailing arguments are not supported.

      • includeAlternateLongIdentifiers

        protected boolean includeAlternateLongIdentifiers()
        Indicates whether the LDAP-specific arguments should include alternate versions of all long identifiers that consist of multiple words so that they are available in both camelCase and dash-separated versions.
        Overrides:
        includeAlternateLongIdentifiers in class MultiServerLDAPCommandLineTool
        Returns:
        true if this tool should provide multiple versions of long identifiers for LDAP-specific arguments, or false if not.

      • supportsPropertiesFile

        public boolean supportsPropertiesFile()
        Indicates whether this tool supports the use of a properties file for specifying default values for arguments that aren't specified on the command line.
        Overrides:
        supportsPropertiesFile in class CommandLineTool
        Returns:
        true if this tool supports the use of a properties file for specifying default values for arguments that aren't specified on the command line, or false if not.

      • logToolInvocationByDefault

        protected boolean logToolInvocationByDefault()
        Indicates whether to log messages about the launch and completion of this tool into the invocation log of Ping Identity server products that may include it. This method is not needed for tools that are not expected to be part of the Ping Identity server products suite. Further, this value may be overridden by settings in the server's tool-invocation-logging.properties file.

        This method should generally return true for tools that may alter the server configuration, data, or other state information, and false for tools that do not make any changes.
        Overrides:
        logToolInvocationByDefault in class CommandLineTool
        Returns:
        true if Ping Identity server products should include messages about the launch and completion of this tool in tool invocation log files by default, or false if not.

      • getToolCompletionMessage

        @Nullable
protected java.lang.String getToolCompletionMessage()
        Retrieves an optional message that may provide additional information about the way that the tool completed its processing. For example if the tool exited with an error message, it may be useful for this method to return that error message.

        The message returned by this method is intended for informational purposes and is not meant to be parsed or programmatically interpreted.
        Overrides:
        getToolCompletionMessage in class CommandLineTool
        Returns:
        An optional message that may provide additional information about the completion state for this tool, or null if no completion message is available.

      • getExampleUsages

        @NotNull
public java.util.LinkedHashMap<java.lang.String[],​java.lang.String> getExampleUsages()
        Retrieves a set of information that may be used to generate example usage information. Each element in the returned map should consist of a map between an example set of arguments and a string that describes the behavior of the tool when invoked with that set of arguments.
        Overrides:
        getExampleUsages in class CommandLineTool
        Returns:
        A set of information that may be used to generate example usage information. It may be null or empty if no example usage information is available.