Class 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.
    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. They include:
    • 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, 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 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 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

        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 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​(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

        protected java.util.List<ControlgetBindControls()
        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

        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.
      • 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 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)
        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 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

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