com.unboundid.ldap.sdk.unboundidds.tools

Class LDAPDiff

java.lang.Object

com.unboundid.util.CommandLineTool

com.unboundid.util.MultiServerLDAPCommandLineTool

com.unboundid.ldap.sdk.unboundidds.tools.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 Summary

Constructors

Constructor and Description
LDAPDiff(java.io.OutputStream out, java.io.OutputStream err) Creates a new instance of this tool with the provided information.

Method Summary

Modifier and Type	Method and Description
void	addNonLDAPArguments(ArgumentParser parser) Adds the arguments needed by this command-line tool to the provided argument parser which are not related to connecting or authenticating to the directory server.
void	doExtendedNonLDAPArgumentValidation() Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid.
ResultCode	doToolProcessing() Performs the core set of processing for this tool.
java.util.List<java.lang.String>	getAdditionalDescriptionParagraphs() Retrieves additional paragraphs that should be included in the description for this tool.
LDAPConnectionOptions	getConnectionOptions() Retrieves the connection options that should be used for connections that are created with this command line tool.
java.util.LinkedHashMap<java.lang.String[],java.lang.String>	getExampleUsages() Retrieves a set of information that may be used to generate example usage information.
int	getMaxTrailingArguments() Retrieves the maximum number of unnamed trailing arguments that may be provided for this tool.
int	getMinTrailingArguments() Retrieves the minimum number of unnamed trailing arguments that must be provided for this tool.
protected java.lang.String	getToolCompletionMessage() Retrieves an optional message that may provide additional information about the way that the tool completed its processing.
java.lang.String	getToolDescription() Retrieves a human-readable description for this tool.
java.lang.String	getToolName() Retrieves the name of this tool.
java.lang.String	getToolVersion() Retrieves a version string for this tool, if available.
java.lang.String	getTrailingArgumentsPlaceholder() Retrieves a placeholder string that should be used for trailing arguments in the usage information for this tool.
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.
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.
static ResultCode	main(java.io.OutputStream out, java.io.OutputStream err, java.lang.String... args) Invokes this tool using the provided set of command-line arguments.
static void	main(java.lang.String... args) Invokes this tool using the provided set of command-line arguments.
protected boolean	supportsDebugLogging() Indicates whether this tool supports the ability to generate a debug log file.
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.

Methods inherited from class com.unboundid.util.MultiServerLDAPCommandLineTool

addToolArguments, createBindRequest, createServerSet, createSSLUtil, doExtendedArgumentValidation, getConnection, getConnectionPool, getUnauthenticatedConnection

Methods inherited from class com.unboundid.util.CommandLineTool

addEnableSSLDebuggingArgument, createArgumentParser, defaultsToInteractiveMode, doShutdownHookProcessing, err, getErr, getOriginalErr, getOriginalOut, getOut, getPasswordFileReader, out, registerShutdownHook, requestToolArgumentsInteractively, runTool, supportsInteractiveMode, supportsOutputFile, wrapErr, wrapOut

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

getToolDescription

@NotNull
public java.lang.String getToolDescription()

Retrieves a human-readable description for this tool. If the description should include multiple paragraphs, then this method should return the text for the first paragraph, and the CommandLineTool.getAdditionalDescriptionParagraphs() method should be used to return the text for the subsequent paragraphs.

Specified by:

getToolDescription in class CommandLineTool

Returns:

A human-readable description 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.

getToolVersion

@NotNull
public java.lang.String getToolVersion()

Retrieves a version string for this tool, if available.

Overrides:

getToolVersion in class CommandLineTool

Returns:

A version string for this tool, or null if none is available.

getConnectionOptions

@NotNull
public LDAPConnectionOptions getConnectionOptions()

Retrieves the connection options that should be used for connections that are created with this command line tool. Subclasses may override this method to use a custom set of connection options.

Overrides:

getConnectionOptions in class MultiServerLDAPCommandLineTool

Returns:

The connection options that should be used for connections that are created with this command line tool.

getMinTrailingArguments

public int getMinTrailingArguments()

Retrieves the minimum number of unnamed trailing arguments that must be provided for this tool. If a tool requires the use of trailing arguments, then it must override this method and the CommandLineTool.getMaxTrailingArguments() arguments to return nonzero values, and it must also override the CommandLineTool.getTrailingArgumentsPlaceholder() method to return a non-null value.

Overrides:

getMinTrailingArguments in class CommandLineTool

Returns:

The minimum number of unnamed trailing arguments that may be provided for this tool. A value of zero indicates that the tool may be invoked without any trailing arguments.

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.

addNonLDAPArguments

public void addNonLDAPArguments(@NotNull
                                ArgumentParser parser)
                         throws ArgumentException

Adds the arguments needed by this command-line tool to the provided argument parser which are not related to connecting or authenticating to the directory server.

Specified by:

addNonLDAPArguments in class MultiServerLDAPCommandLineTool

Parameters:

parser - The argument parser to which the arguments should be added.

Throws:

ArgumentException - If a problem occurs while adding the arguments.

doExtendedNonLDAPArgumentValidation

public void doExtendedNonLDAPArgumentValidation()
                                         throws ArgumentException

Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid. This method will be called after the basic argument parsing has been performed and after all LDAP-specific argument validation has been processed, and immediately before the CommandLineTool.doToolProcessing() method is invoked.

Overrides:

doExtendedNonLDAPArgumentValidation in class MultiServerLDAPCommandLineTool

Throws:

ArgumentException - If there was a problem with the command-line arguments provided to this program.

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.

supportsDebugLogging

protected boolean supportsDebugLogging()

Indicates whether this tool supports the ability to generate a debug log file. If this method returns true, then the tool will expose additional arguments that can control debug logging.

Overrides:

supportsDebugLogging in class CommandLineTool

Returns:

true if this tool supports the ability to generate a debug log file, 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.

doToolProcessing

@NotNull
public ResultCode doToolProcessing()

Performs the core set of processing for this tool.

Specified by:

doToolProcessing in class CommandLineTool

Returns:

A result code that indicates whether the processing completed successfully.

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.