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:
- 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.
- 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.
- 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 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. -
Retrieve the DNs from each server in parallel. For servers that
advertise support for the
-
-
Constructor Summary
Constructors Constructor Description LDAPDiff(java.io.OutputStream out, java.io.OutputStream err)
Creates a new instance of this tool with the provided information.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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
-
-
-
-
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 benull
if standard output should be suppressed.err
- The output stream to use for standard error. It may benull
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 benull
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 benull
if standard output should be suppressed.err
- The output stream to use for standard error. It may benull
if standard error should be suppressed.args
- The command-line arguments provided to this program. It must not benull
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 ofResultCode.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 classCommandLineTool
- 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 theCommandLineTool.getAdditionalDescriptionParagraphs()
method should be used to return the text for the subsequent paragraphs.- Specified by:
getToolDescription
in classCommandLineTool
- 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 theCommandLineTool.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 returnnull
or an empty list.- Overrides:
getAdditionalDescriptionParagraphs
in classCommandLineTool
- 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 thegetToolDescription
method) is needed.
-
getToolVersion
@NotNull public java.lang.String getToolVersion()
Retrieves a version string for this tool, if available.- Overrides:
getToolVersion
in classCommandLineTool
- 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 classMultiServerLDAPCommandLineTool
- 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 theCommandLineTool.getMaxTrailingArguments()
arguments to return nonzero values, and it must also override theCommandLineTool.getTrailingArgumentsPlaceholder()
method to return a non-null
value.- Overrides:
getMinTrailingArguments
in classCommandLineTool
- 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 theCommandLineTool.getTrailingArgumentsPlaceholder()
method to return a non-null
value.- Overrides:
getMaxTrailingArguments
in classCommandLineTool
- 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 classCommandLineTool
- 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 classMultiServerLDAPCommandLineTool
- Returns:
true
if this tool should provide multiple versions of long identifiers for LDAP-specific arguments, orfalse
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 classMultiServerLDAPCommandLineTool
- 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 theCommandLineTool.doToolProcessing()
method is invoked.- Overrides:
doExtendedNonLDAPArgumentValidation
in classMultiServerLDAPCommandLineTool
- 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 classCommandLineTool
- 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, orfalse
if not.
-
supportsDebugLogging
protected boolean supportsDebugLogging()
Indicates whether this tool supports the ability to generate a debug log file. If this method returnstrue
, then the tool will expose additional arguments that can control debug logging.- Overrides:
supportsDebugLogging
in classCommandLineTool
- Returns:
true
if this tool supports the ability to generate a debug log file, orfalse
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 returntrue
for tools that may alter the server configuration, data, or other state information, andfalse
for tools that do not make any changes.- Overrides:
logToolInvocationByDefault
in classCommandLineTool
- 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, orfalse
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 classCommandLineTool
- 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 classCommandLineTool
- 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 classCommandLineTool
- 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.
-
-