com.unboundid.util

Class LDAPCommandLineTool

java.lang.Object

com.unboundid.util.CommandLineTool

com.unboundid.util.LDAPCommandLineTool

Direct Known Subclasses:

AuthRate, CollectSupportData, DeliverOneTimePassword, DeliverPasswordResetToken, DumpDNs, GenerateSourceFromSchema, GenerateTOTPSharedSecret, IdentifyReferencesToMissingEntries, IdentifyUniqueAttributeConflicts, LDAPCompare, LDAPCompare, LDAPDebugger, LDAPDelete, LDAPModify, LDAPModify, LDAPPasswordModify, LDAPSearch, LDAPSearch, ManageAccount, ModRate, ParallelUpdate, RegisterYubiKeyOTPDevice, SearchAndModRate, SearchRate, SubtreeAccessibility, ValidateLDIF

@Extensible
 @ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
public abstract class LDAPCommandLineTool
extends CommandLineTool

This class provides a basis for developing command-line tools that communicate with an LDAP directory server. It provides a common set of options for connecting and authenticating to a directory server, and then provides a mechanism for obtaining connections and connection pools to use when communicating with that server.

The arguments that this class supports include:

• "-h {address}" or "--hostname {address}" -- Specifies the address of the directory server. If this isn't specified, then a default of "localhost" will be used.
• "-p {port}" or "--port {port}" -- Specifies the port number of the directory server. If this isn't specified, then a default port of 389 will be used.
• "-D {bindDN}" or "--bindDN {bindDN}" -- Specifies the DN to use to bind to the directory server using simple authentication. If this isn't specified, then simple authentication will not be performed.
• "-w {password}" or "--bindPassword {password}" -- Specifies the password to use when binding with simple authentication or a password-based SASL mechanism.
• "-j {path}" or "--bindPasswordFile {path}" -- Specifies the path to the file containing the password to use when binding with simple authentication or a password-based SASL mechanism.
• "--promptForBindPassword" -- Indicates that the tool should interactively prompt the user for the bind password.
• "-Z" or "--useSSL" -- Indicates that the communication with the server should be secured using SSL.
• "-q" or "--useStartTLS" -- Indicates that the communication with the server should be secured using StartTLS.
• "--defaultTrust" -- Indicates that the client should use a default, non-interactive mechanism for determining whether to trust any presented server certificate.
• "-X" or "--trustAll" -- Indicates that the client should trust any certificate that the server presents to it.
• "-K {path}" or "--keyStorePath {path}" -- Specifies the path to the key store to use to obtain client certificates.
• "-W {password}" or "--keyStorePassword {password}" -- Specifies the password to use to access the contents of the key store.
• "-u {path}" or "--keyStorePasswordFile {path}" -- Specifies the path to the file containing the password to use to access the contents of the key store.
• "--promptForKeyStorePassword" -- Indicates that the tool should interactively prompt the user for the key store password.
• "--keyStoreFormat {format}" -- Specifies the format to use for the key store file.
• "-P {path}" or "--trustStorePath {path}" -- Specifies the path to the trust store to use when determining whether to trust server certificates.
• "-T {password}" or "--trustStorePassword {password}" -- Specifies the password to use to access the contents of the trust store.
• "-U {path}" or "--trustStorePasswordFile {path}" -- Specifies the path to the file containing the password to use to access the contents of the trust store.
• "--promptForTrustStorePassword" -- Indicates that the tool should interactively prompt the user for the trust store password.
• "--trustStoreFormat {format}" -- Specifies the format to use for the trust store file.
• "--verifyCertificateHostnames" -- Indicates that the tool should verify that the hostname or IP address used to establish connections to the LDAP server matches an address for which the server's TLS certificate was issued.
• "-N {nickname}" or "--certNickname {nickname}" -- Specifies the nickname of the client certificate to use when performing SSL client authentication.
• "--enableSSLDebugging" -- Indicates that the tool should display detailed information about all TLS-related processing that it is performing.
• "-o {name=value}" or "--saslOption {name=value}" -- Specifies a SASL option to use when performing SASL authentication.
• "--useSASLExternal" -- Indicates that the SASL EXTERNAL mechanism should be used to authenticate the connection with information that the client has provided to the server outside the LDAP layer (for example, using a client certificate). This is equivalent to "--saslOption mech=EXTERNAL"

If SASL authentication is to be used, then a "mech" SASL option must be provided to specify the name of the SASL mechanism to use (e.g., "--saslOption mech=EXTERNAL" indicates that the EXTERNAL mechanism should be used). Depending on the SASL mechanism, additional SASL options may be required or optional. Use the "--help-sasl" argument to see a list of all supported SASL mechanisms and the arguments that can be used with each of them.

Note that in general, methods in this class are not threadsafe. However, the getConnection() and getConnectionPool(int,int) methods may be invoked concurrently by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.

Constructor Summary

Constructors

Constructor and Description
LDAPCommandLineTool(java.io.OutputStream outStream, java.io.OutputStream errStream) Creates a new instance of this LDAP-enabled command-line tool with the provided information.

Method Summary

Modifier and Type	Method and Description
abstract 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	addToolArguments(ArgumentParser parser) Adds the command-line arguments supported for use with this tool to the provided argument parser.
boolean	anyLDAPArgumentsProvided() Indicates whether any of the LDAP-related arguments maintained by the LDAPCommandLineTool class were provided on the command line.
BindRequest	createBindRequest() Creates the bind request to use to authenticate to the server.
ServerSet	createServerSet() Creates the server set to use when creating connections or connection pools.
SSLUtil	createSSLUtil() Creates the SSLUtil instance to use for secure communication.
SSLUtil	createSSLUtil(boolean force) Creates the SSLUtil instance to use for secure communication.
protected boolean	defaultToPromptForBindPassword() Indicates whether this tool should default to interactively prompting for the bind password if a password is required but no argument was provided to indicate how to get the password.
void	doExtendedArgumentValidation() Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid.
void	doExtendedNonLDAPArgumentValidation() Performs any necessary processing that should be done to ensure that the provided set of command-line arguments were valid.
protected java.util.List<Control>	getBindControls() Retrieves a set of controls that should be included in any bind request generated by this tool.
LDAPConnection	getConnection() Retrieves a connection that may be used to communicate with the target directory server.
LDAPConnectionOptions	getConnectionOptions() Retrieves the connection options that should be used for connections that are created with this command line tool.
protected LDAPConnectionOptions	getConnectionOptionsWithRequestedSettings() Retrieves the connection options that should be used for connections that are created with this command-line tool, including any options that may be set as a result of command-line arguments.
LDAPConnectionPool	getConnectionPool(int initialConnections, int maxConnections) Retrieves a connection pool that may be used to communicate with the target directory server.
LDAPConnectionPool	getConnectionPool(int initialConnections, int maxConnections, int initialConnectThreads, PostConnectProcessor beforeStartTLSProcessor, PostConnectProcessor afterStartTLSProcessor, boolean throwOnConnectFailure, LDAPConnectionPoolHealthCheck healthCheck) Retrieves a connection pool that may be used to communicate with the target directory server.
protected java.util.Set<java.lang.Character>	getSuppressedShortIdentifiers() Retrieves a set containing any short identifiers that should be suppressed in the set of generic tool arguments so that they can be used by a tool-specific argument instead.
LDAPConnection	getUnauthenticatedConnection() Retrieves an unauthenticated connection that may be used to communicate with the target directory server.
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	supportsAuthentication() Indicates whether this tool should provide the arguments that allow it to bind via simple or SASL authentication.
protected boolean	supportsMultipleServers() Indicates whether this tool supports creating connections to multiple servers.
protected boolean	supportsSASLHelp() Indicates whether this tool should provide a "--help-sasl" argument that provides information about the supported SASL mechanisms and their associated properties.
protected boolean	supportsSSLDebugging() Indicates whether this tool should provide a command-line argument that allows for low-level SSL debugging.

Methods inherited from class com.unboundid.util.CommandLineTool

addEnableSSLDebuggingArgument, createArgumentParser, defaultsToInteractiveMode, doShutdownHookProcessing, doToolProcessing, err, getAdditionalDescriptionParagraphs, getErr, getExampleUsages, getMaxTrailingArguments, getMinTrailingArguments, getOriginalErr, getOriginalOut, getOut, getPasswordFileReader, getToolCompletionMessage, getToolDescription, getToolName, getToolVersion, getTrailingArgumentsPlaceholder, logToolInvocationByDefault, out, registerShutdownHook, requestToolArgumentsInteractively, runTool, supportsDebugLogging, supportsInteractiveMode, supportsOutputFile, supportsPropertiesFile, wrapErr, wrapOut

Methods inherited from class java.lang.Object

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

Constructor Detail

LDAPCommandLineTool

public LDAPCommandLineTool(@Nullable
                           java.io.OutputStream outStream,
                           @Nullable
                           java.io.OutputStream errStream)

Creates a new instance of this LDAP-enabled command-line tool with the provided information.

Parameters:

outStream - The output stream to use for standard output. It may be System.out for the JVM's default standard output stream, null if no output should be generated, or a custom output stream if the output should be sent to an alternate location.

errStream - The output stream to use for standard error. It may be System.err for the JVM's default standard error stream, null if no output should be generated, or a custom output stream if the output should be sent to an alternate location.

Method Detail

getSuppressedShortIdentifiers

@NotNull
protected java.util.Set<java.lang.Character> getSuppressedShortIdentifiers()

Retrieves a set containing any short identifiers that should be suppressed in the set of generic tool arguments so that they can be used by a tool-specific argument instead.

Returns:

A set containing any short identifiers that should be suppressed in the set of generic tool arguments so that they can be used by a tool-specific argument instead. It may be empty but must not be null.

addToolArguments

public final void addToolArguments(@NotNull
                                   ArgumentParser parser)
                            throws ArgumentException

Adds the command-line arguments supported for use with this tool to the provided argument parser. The tool may need to retain references to the arguments (and/or the argument parser, if trailing arguments are allowed) to it in order to obtain their values for use in later processing.

Specified by:

addToolArguments in class CommandLineTool

Parameters:

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

Throws:

ArgumentException - If a problem occurs while adding any of the tool-specific arguments to the provided argument parser.

addNonLDAPArguments

public abstract 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.

Parameters:

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

Throws:

ArgumentException - If a problem occurs while adding the arguments.

doExtendedArgumentValidation

public final void doExtendedArgumentValidation()
                                        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 immediately before the CommandLineTool.doToolProcessing() method is invoked. Note that if the tool supports interactive mode, then this method may be invoked multiple times to allow the user to interactively fix validation errors.

Overrides:

doExtendedArgumentValidation in class CommandLineTool

Throws:

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

supportsAuthentication

protected boolean supportsAuthentication()

Indicates whether this tool should provide the arguments that allow it to bind via simple or SASL authentication.

Returns:

true if this tool should provide the arguments that allow it to bind via simple or SASL authentication, or false if not.

defaultToPromptForBindPassword

protected boolean defaultToPromptForBindPassword()

Indicates whether this tool should default to interactively prompting for the bind password if a password is required but no argument was provided to indicate how to get the password.

Returns:

true if this tool should default to interactively prompting for the bind password, or false if not.

supportsSASLHelp

protected boolean supportsSASLHelp()

Indicates whether this tool should provide a "--help-sasl" argument that provides information about the supported SASL mechanisms and their associated properties.

Returns:

true if this tool should provide a "--help-sasl" argument, or false if not.

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.

Returns:

true if this tool should provide multiple versions of long identifiers for LDAP-specific arguments, or false if not.

getBindControls

@Nullable
protected java.util.List<Control> getBindControls()

Retrieves a set of controls that should be included in any bind request generated by this tool.

Returns:

A set of controls that should be included in any bind request generated by this tool. It may be null or empty if no controls should be included in the bind request.

supportsMultipleServers

protected boolean supportsMultipleServers()

Indicates whether this tool supports creating connections to multiple servers. If it is to support multiple servers, then the "--hostname" and "--port" arguments will be allowed to be provided multiple times, and will be required to be provided the same number of times. The same type of communication security and bind credentials will be used for all servers.

Returns:

true if this tool supports creating connections to multiple servers, or false if not.

supportsSSLDebugging

protected boolean supportsSSLDebugging()

Indicates whether this tool should provide a command-line argument that allows for low-level SSL debugging. If this returns true, then an "--enableSSLDebugging" argument will be added that sets the "javax.net.debug" system property to "all" before attempting any communication.

Returns:

true if this tool should offer an "--enableSSLDebugging" argument, or false if not.

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.

Throws:

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

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.

Returns:

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

getConnectionOptionsWithRequestedSettings

@NotNull
protected final LDAPConnectionOptions getConnectionOptionsWithRequestedSettings()

Retrieves the connection options that should be used for connections that are created with this command-line tool, including any options that may be set as a result of command-line arguments. This method will return a copy of the connection options retrieved from the getConnectionOptions() method, but with any alterations applied as appropriate for the configured set of command-line options.

Returns:

The connection options that should be used for connections that are created with this command-line tool, including any options that may be set as a result of command-line arguments.

getConnection

@ThreadSafety(level=METHOD_THREADSAFE)
 @NotNull
public final LDAPConnection getConnection()
                                                                                    throws LDAPException

Retrieves a connection that may be used to communicate with the target directory server.

Note that this method is threadsafe and may be invoked by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.

Returns:

A connection that may be used to communicate with the target directory server.

Throws:

LDAPException - If a problem occurs while creating the connection.

getUnauthenticatedConnection

@ThreadSafety(level=METHOD_THREADSAFE)
 @NotNull
public final LDAPConnection getUnauthenticatedConnection()
                                                                                                   throws LDAPException

Retrieves an unauthenticated connection that may be used to communicate with the target directory server.

Note that this method is threadsafe and may be invoked by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.

Returns:

An unauthenticated connection that may be used to communicate with the target directory server.

Throws:

LDAPException - If a problem occurs while creating the connection.

getConnectionPool

@ThreadSafety(level=METHOD_THREADSAFE)
 @NotNull
public final LDAPConnectionPool getConnectionPool(int initialConnections,
                                                                                                   int maxConnections)
                                                                                            throws LDAPException

Retrieves a connection pool that may be used to communicate with the target directory server.

Note that this method is threadsafe and may be invoked by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.

Parameters:

initialConnections - The number of connections that should be initially established in the pool.

maxConnections - The maximum number of connections to maintain in the pool.

Returns:

A connection that may be used to communicate with the target directory server.

Throws:

LDAPException - If a problem occurs while creating the connection pool.

getConnectionPool

@ThreadSafety(level=METHOD_THREADSAFE)
 @NotNull
public final LDAPConnectionPool getConnectionPool(int initialConnections,
                                                                                                   int maxConnections,
                                                                                                   int initialConnectThreads,
                                                                                                   @Nullable
                                                                                                   PostConnectProcessor beforeStartTLSProcessor,
                                                                                                   @Nullable
                                                                                                   PostConnectProcessor afterStartTLSProcessor,
                                                                                                   boolean throwOnConnectFailure,
                                                                                                   @Nullable
                                                                                                   LDAPConnectionPoolHealthCheck healthCheck)
                                                                                            throws LDAPException

Retrieves a connection pool that may be used to communicate with the target directory server.

Note that this method is threadsafe and may be invoked by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.

Parameters:

initialConnections - The number of connections that should be initially established in the pool.

maxConnections - The maximum number of connections to maintain in the pool.

initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.

beforeStartTLSProcessor - An optional post-connect processor that should be used for the connection pool and should be invoked before any StartTLS post-connect processor that may be needed based on the selected arguments. It may be null if no such post-connect processor is needed.

afterStartTLSProcessor - An optional post-connect processor that should be used for the connection pool and should be invoked after any StartTLS post-connect processor that may be needed based on the selected arguments. It may be null if no such post-connect processor is needed.

throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).

healthCheck - An optional health check that should be configured for the connection pool. It may be null if the default health checking should be performed.

Returns:

A connection that may be used to communicate with the target directory server.

Throws:

LDAPException - If a problem occurs while creating the connection pool.

createServerSet

@NotNull
public ServerSet createServerSet()
                                   throws LDAPException

Creates the server set to use when creating connections or connection pools.

Returns:

The server set to use when creating connections or connection pools.

Throws:

LDAPException - If a problem occurs while creating the server set.

createSSLUtil

@Nullable
public SSLUtil createSSLUtil()
                                throws LDAPException

Creates the SSLUtil instance to use for secure communication.

Returns:

The SSLUtil instance to use for secure communication, or null if secure communication is not needed.

Throws:

LDAPException - If a problem occurs while creating the SSLUtil instance.

createSSLUtil

@Nullable
public SSLUtil createSSLUtil(boolean force)
                                throws LDAPException

Creates the SSLUtil instance to use for secure communication.

Parameters:

force - Indicates whether to create the SSLUtil object even if neither the "--useSSL" nor the "--useStartTLS" argument was provided. The key store and/or trust store paths must still have been provided. This may be useful for tools that accept SSL-based communication but do not themselves intend to perform SSL-based communication as an LDAP client.

Returns:

The SSLUtil instance to use for secure communication, or null if secure communication is not needed.

Throws:

LDAPException - If a problem occurs while creating the SSLUtil instance.

createBindRequest

@Nullable
public BindRequest createBindRequest()
                                        throws LDAPException

Creates the bind request to use to authenticate to the server.

Returns:

The bind request to use to authenticate to the server, or null if no bind should be performed.

Throws:

LDAPException - If a problem occurs while creating the bind request.

anyLDAPArgumentsProvided

public final boolean anyLDAPArgumentsProvided()

Indicates whether any of the LDAP-related arguments maintained by the LDAPCommandLineTool class were provided on the command line.

Returns:

true if any of the LDAP-related arguments maintained by the LDAPCommandLineTool were provided on the command line, or false if not.