Class MultiServerLDAPCommandLineTool

  • Direct Known Subclasses:
    LDAPDiff, MoveSubtree

    @Extensible
    @ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
    public abstract class MultiServerLDAPCommandLineTool
    extends CommandLineTool
    This class provides a basis for developing command-line tools that have the ability to communicate with multiple directory servers, potentially with very different settings for each. For example, it may be used to help create tools that move or compare data from one server to another.

    Each server will be identified by a prefix and/or suffix that will be added to the argument name (e.g., if the first server has a prefix of "source", then the "hostname" argument will actually be "sourceHostname"). The base names for the arguments this class supports include:
    • hostname -- Specifies the address of the directory server. If this isn't specified, then a default of "localhost" will be used.
    • port -- specifies the port number of the directory server. If this isn't specified, then a default port of 389 will be used.
    • 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.
    • bindPassword -- Specifies the password to use when binding with simple authentication or a password-based SASL mechanism.
    • bindPasswordFile -- Specifies the path to a file containing the password to use when binding with simple authentication or a password-based SASL mechanism.
    • useSSL -- Indicates that communication with the server should be secured using SSL.
    • useStartTLS -- Indicates that 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.
    • trustAll -- Indicates that the client should trust any certificate that the server presents to it.
    • keyStorePath -- Specifies the path to the key store to use to obtain client certificates.
    • keyStorePassword -- Specifies the password to use to access the contents of the key store.
    • keyStorePasswordFile -- Specifies the path ot a file containing the password to use to access the contents of the key store.
    • keyStoreFormat -- Specifies the format to use for the key store file.
    • trustStorePath -- Specifies the path to the trust store to use to obtain client certificates.
    • trustStorePassword -- Specifies the password to use to access the contents of the trust store.
    • trustStorePasswordFile -- Specifies the path ot a file containing the password to use to access the contents of the trust store.
    • trustStoreFormat -- Specifies the format to use for the trust store file.
    • certNickname -- Specifies the nickname of the client certificate to use when performing SSL client authentication.
    • saslOption -- 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. Depending on the SASL mechanism, additional SASL options may be required or optional.
    • Constructor Detail

      • MultiServerLDAPCommandLineTool

        public MultiServerLDAPCommandLineTool​(@Nullable
                                              java.io.OutputStream outStream,
                                              @Nullable
                                              java.io.OutputStream errStream,
                                              @Nullable
                                              java.lang.String[] serverNamePrefixes,
                                              @Nullable
                                              java.lang.String[] serverNameSuffixes)
                                       throws LDAPSDKUsageException
        Creates a new instance of this multi-server LDAP command-line tool. At least one of the set of server name prefixes and suffixes must be non-null. If both are non-null, then they must have the same number of elements.
        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.
        serverNamePrefixes - The prefixes to include before the names of each of the parameters to identify each server. It may be null if only suffixes should be used.
        serverNameSuffixes - The suffixes to include after the names of each of the parameters to identify each server. It may be null if only prefixes should be used.
        Throws:
        LDAPSDKUsageException - If both the sets of server name prefixes and suffixes are null or empty, or if both sets are non-null but have different numbers of elements.
    • Method Detail

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

        @ThreadSafety(level=METHOD_THREADSAFE)
        @NotNull
        public final LDAPConnection getConnection​(int serverIndex)
                                           throws LDAPException
        Retrieves a connection that may be used to communicate with the indicated 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:
        serverIndex - The zero-based index of the server to which the connection should be established.
        Returns:
        A connection that may be used to communicate with the indicated directory server.
        Throws:
        LDAPException - If a problem occurs while creating the connection.
      • getUnauthenticatedConnection

        @ThreadSafety(level=METHOD_THREADSAFE)
        @NotNull
        public final LDAPConnection getUnauthenticatedConnection​(int serverIndex)
                                                          throws LDAPException
        Retrieves an unauthenticated connection that may be used to communicate with the indicated 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:
        serverIndex - The zero-based index of the server to which the connection should be established.
        Returns:
        An unauthenticated connection that may be used to communicate with the indicated directory server.
        Throws:
        LDAPException - If a problem occurs while creating the connection.
      • getConnectionPool

        @ThreadSafety(level=METHOD_THREADSAFE)
        @NotNull
        public final LDAPConnectionPool getConnectionPool​(int serverIndex,
                                                          int initialConnections,
                                                          int maxConnections)
                                                   throws LDAPException
        Retrieves a connection pool that may be used to communicate with the indicated 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:
        serverIndex - The zero-based index of the server to which the connection should be established.
        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 indicated directory server.
        Throws:
        LDAPException - If a problem occurs while creating the connection pool.
      • createServerSet

        @NotNull
        public final ServerSet createServerSet​(int serverIndex)
                                        throws LDAPException
        Creates the server set to use when creating connections or connection pools.
        Parameters:
        serverIndex - The zero-based index of the server to which the connection should be established.
        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 final SSLUtil createSSLUtil​(int serverIndex)
                                    throws LDAPException
        Creates the SSLUtil instance to use for secure communication.
        Parameters:
        serverIndex - The zero-based index of the server to which the connection should be established.
        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 final BindRequest createBindRequest​(int serverIndex)
                                            throws LDAPException
        Creates the bind request to use to authenticate to the indicated server.
        Parameters:
        serverIndex - The zero-based index of the server to which the connection should be established.
        Returns:
        The bind request to use to authenticate to the indicated server, or null if no bind should be performed.
        Throws:
        LDAPException - If a problem occurs while creating the bind request.