Package 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
,LDAPDebugger
,LDAPDelete
,LDAPModify
,LDAPModify
,LDAPSearch
,LDAPSearch
,ManageAccount
,ModRate
,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.
- "-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.
- "-N {nickname}" or "--certNickname {nickname}" -- Specifies the nickname of the client certificate to use when performing SSL client authentication.
- "-o {name=value}" or "--saslOption {name=value}" -- Specifies a SASL option to use when performing SASL authentication.
-
mech=ANONYMOUS
- Required SASL options:
- Optional SASL options: trace
-
mech=CRAM-MD5
- Required SASL options: authID
- Optional SASL options:
-
mech=DIGEST-MD5
- Required SASL options: authID
- Optional SASL options: authzID, realm
-
mech=EXTERNAL
- Required SASL options:
- Optional SASL options:
-
mech=GSSAPI
- Required SASL options: authID
- Optional SASL options: authzID, configFile, debug, protocol, realm, kdcAddress, useTicketCache, requireCache, renewTGT, ticketCachePath
-
mech=PLAIN
- Required SASL options: authID
- Optional SASL options: authzID
Note that in general, methods in this class are not threadsafe. However, thegetConnection()
andgetConnectionPool(int,int)
methods may be invoked concurrently by multiple threads accessing the same instance only while that instance is in the process of invoking theCommandLineTool.doToolProcessing()
method.
-
-
Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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 theLDAPCommandLineTool
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.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, supportsInteractiveMode, supportsOutputFile, supportsPropertiesFile, wrapErr, wrapOut
-
-
-
-
Constructor Detail
-
LDAPCommandLineTool
public LDAPCommandLineTool(java.io.OutputStream outStream, 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 beSystem.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 beSystem.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
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(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 classCommandLineTool
- 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(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 theCommandLineTool.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 classCommandLineTool
- 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, orfalse
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, orfalse
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, orfalse
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, orfalse
if not.
-
getBindControls
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, orfalse
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 returnstrue
, 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, orfalse
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 theCommandLineTool.doToolProcessing()
method is invoked.- Throws:
ArgumentException
- If there was a problem with the command-line arguments provided to this program.
-
getConnectionOptions
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.
-
getConnection
@ThreadSafety(level=METHOD_THREADSAFE) 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 theCommandLineTool.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) 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 theCommandLineTool.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) 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 theCommandLineTool.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) public final LDAPConnectionPool getConnectionPool(int initialConnections, int maxConnections, int initialConnectThreads, PostConnectProcessor beforeStartTLSProcessor, PostConnectProcessor afterStartTLSProcessor, boolean throwOnConnectFailure, 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 theCommandLineTool.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 benull
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 benull
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. Iftrue
, then the attempt to create the pool will fail if any connection cannot be established. Iffalse
, 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 benull
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
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
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
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
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 theLDAPCommandLineTool
class were provided on the command line.- Returns:
true
if any of the LDAP-related arguments maintained by theLDAPCommandLineTool
were provided on the command line, orfalse
if not.
-
-