Class InMemoryDirectoryServerTool

  • All Implemented Interfaces:
    LDAPListenerExceptionHandler, java.io.Serializable

    @NotMutable
    @ThreadSafety(level=NOT_THREADSAFE)
    public final class InMemoryDirectoryServerTool
    extends CommandLineTool
    implements java.io.Serializable, LDAPListenerExceptionHandler
    This class provides a command-line tool that can be used to run an instance of the in-memory directory server. Instances of the server may also be created and controlled programmatically using the InMemoryDirectoryServer class.

    The following command-line arguments may be used with this class:
    • "-b {baseDN}" or "--baseDN {baseDN}" -- specifies a base DN to use for the server. At least one base DN must be specified, and multiple base DNs may be provided as separate arguments.
    • "-p {port}" or "--port {port}" -- specifies the port on which the server should listen for client connections. If this is not provided, then a free port will be automatically chosen for use by the server.
    • "-l {path}" or "--ldifFile {path}" -- specifies the path to an LDIF file to use to initially populate the server. If this is not provided, then the server will initially be empty. The LDIF file will not be updated as operations are processed in the server.
    • "-D {bindDN}" or "--additionalBindDN {bindDN}" -- specifies an additional DN that can be used to authenticate to the server, even if there is no account for that user. If this is provided, then the --additionalBindPassword argument must also be given.
    • "-w {password}" or "--additionalBindPassword {password}" -- specifies the password that should be used when attempting to bind as the user specified with the "-additionalBindDN" argument. If this is provided, then the --additionalBindDN argument must also be given.
    • "-c {count}" or "--maxChangeLogEntries {count}" -- Indicates whether an LDAP changelog should be enabled, and if so how many changelog records should be maintained. If this argument is not provided, or if it is provided with a value of zero, then no changelog will be maintained.
    • "-A" or "--accessLogToStandardOut" -- indicates that access log information should be written to standard output. This cannot be provided in conjunction with the "--accessLogFile" argument. If neither argument is provided, then no access logging will be performed
    • "-a {path}" or "--accessLogFile {path}" -- specifies the path to a file that should be used as a server access log. This cannot be provided in conjunction with the "--accessLogToStandardOut" argument. If neither argument is provided, then no access logging will be performed
    • "---jsonAccessLogToStandardOut" -- indicates that JSON-formatted access log information should be written to standard output. This cannot be provided in conjunction with the "--jsonAccessLogFile" argument. If neither argument is provided, then no JSON-formatted access logging will be performed
    • "--jsonAccessLogFile {path}" -- specifies the path to a file that should be used as a server access log with JSON-formatted messages. This cannot be provided in conjunction with the "--jsonAccessLogToStandardOut" argument. If neither argument is provided, then no JSON-formatted access logging will be performed
    • "--ldapDebugLogToStandardOut" -- Indicates that LDAP debug log information should be written to standard output. This cannot be provided in conjunction with the "--ldapDebugLogFile" argument. If neither argument is provided, then no debug logging will be performed.
    • "-d {path}" or "--ldapDebugLogFile {path}" -- specifies the path to a file that should be used as a server LDAP debug log. This cannot be provided in conjunction with the "--ldapDebugLogToStandardOut" argument. If neither argument is provided, then no debug logging will be performed.
    • "-s" or "--useDefaultSchema" -- Indicates that the server should use the default standard schema provided as part of the LDAP SDK. If neither this argument nor the "--useSchemaFile" argument is provided, then the server will not perform any schema validation.
    • "-S {path}" or "--useSchemaFile {path}" -- specifies the path to a file or directory containing schema definitions to use for the server. If neither this argument nor the "--useDefaultSchema" argument is provided, then the server will not perform any schema validation. If the specified path represents a file, then it must be an LDIF file containing a valid LDAP subschema subentry. If the path is a directory, then its files will be processed in lexicographic order by name.
    • "-I {attr}" or "--equalityIndex {attr}" -- specifies that an equality index should be maintained for the specified attribute. The equality index may be used to speed up certain kinds of searches, although it will cause the server to consume more memory.
    • "-Z" or "--useSSL" -- indicates that the server should encrypt all communication using SSL. If this is provided, then the "--keyStorePath" and "--keyStorePassword" arguments must also be provided, and the "--useStartTLS" argument must not be provided.
    • "-q" or "--useStartTLS" -- indicates that the server should support the use of the StartTLS extended request. If this is provided, then the "--keyStorePath" and "--keyStorePassword" arguments must also be provided, and the "--useSSL" argument must not be provided.
    • "-K {path}" or "--keyStorePath {path}" -- specifies the path to the JKS key store file that should be used to obtain the server certificate to use for SSL communication. If this argument is provided, then the "--keyStorePassword" argument must also be provided, along with exactly one of the "--useSSL" or "--useStartTLS" arguments.
    • "-W {password}" or "--keyStorePassword {password}" -- specifies the password that should be used to access the contents of the SSL key store. If this argument is provided, then the "--keyStorePath" argument must also be provided, along with exactly one of the "--useSSL" or "--useStartTLS" arguments.
    • "--keyStoreType {type}" -- specifies the type of keystore represented by the file specified by the keystore path. If this argument is provided, then the "--keyStorePath" argument must also be provided, along with exactly one of the "--useSSL" or "--useStartTLS" arguments. If this argument is not provided, then a default key store type of "JKS" will be assumed.
    • "--generateSelfSignedCertificate" -- indicates that the server should generate a self-signed certificate to use for SSL or StartTLS communication. If this argument is provided, then exactly one of the "--useSSL" or "--useStartTLS" arguments must also be specified.
    • "-P {path}" or "--trustStorePath {path}" -- specifies the path to the JKS trust store file that should be used to determine whether to trust any SSL certificates that may be presented by the client. If this argument is provided, then exactly one of the "--useSSL" or "--useStartTLS" arguments must also be provided. If this argument is not provided but SSL or StartTLS is to be used, then all client certificates will be automatically trusted.
    • "-T {password}" or "--trustStorePassword {password}" -- specifies the password that should be used to access the contents of the SSL trust store. If this argument is provided, then the "--trustStorePath" argument must also be provided, along with exactly one of the "--useSSL" or "--useStartTLS" arguments. If an SSL trust store path was provided without a trust store password, then the server will attempt to use the trust store without a password.
    • "--trustStoreType {type}" -- specifies the type of trust store represented by the file specified by the trust store path. If this argument is provided, then the "--trustStorePath" argument must also be provided, along with exactly one of the "--useSSL" or "--useStartTLS" arguments. If this argument is not provided, then a default trust store type of "JKS" will be assumed.
    • "--maxConcurrentConnections {num}" -- specifies the maximum number of concurrent connections that the server will allow.
    • "--sizeLimit {num}" -- specifies the maximum number of entries that the server will reeturn for a single search operation.
    • "--passwordAttribute {attr}" -- specifies an attribute that will hold user passwords.
    • "--defaultPasswordEncoding {scheme}" -- specifies the name of the default scheme that the server will use to encode clear-text passwords. Allowed values include MD5, SMD5, SHA, SSHA, SHA256, SSHA256, SHA384, SSHA384, SHA512, SSHA512, CLEAR, BASE64, and HEX.
    • "--allowedOperationType {type}" -- specifies a type of operation that the server will allow. Allowed values include add, bind, compare, delete, extended, modify, modify-dn, and search.
    • "--authenticationRequiredOperationType {type}" -- specifies a type of operation that the server will only allow for authenticated clients. Allowed values include add, compare, delete, extended, modify, modify-dn, and search.
    • "--vendorName {name}" -- specifies the vendor name value to appear in the server root DSE.
    • "--vendorVersion {version}" -- specifies the vendor version value to appear in the server root DSE.
    See Also:
    Serialized Form
    • Constructor Detail

      • InMemoryDirectoryServerTool

        public InMemoryDirectoryServerTool​(java.io.OutputStream outStream,
                                           java.io.OutputStream errStream)
        Creates a new instance of this tool that use the provided output streams for standard output and standard error.
        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

      • main

        public static void main​(java.lang.String... args)
        Parse the provided command line arguments and uses them to start the directory server.
        Parameters:
        args - The command line arguments provided to this program.
      • main

        public static ResultCode main​(java.lang.String[] args,
                                      java.io.OutputStream outStream,
                                      java.io.OutputStream errStream)
        Parse the provided command line arguments and uses them to start the directory server.
        Parameters:
        outStream - The output stream to which standard out should be written. It may be null if output should be suppressed.
        errStream - The output stream to which standard error should be written. It may be null if error messages should be suppressed.
        args - The command line arguments provided to this program.
        Returns:
        A result code indicating whether the processing was successful.
      • getToolName

        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 class CommandLineTool
        Returns:
        The name for this tool.
      • addToolArguments

        public 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.
      • supportsInteractiveMode

        public boolean supportsInteractiveMode()
        Indicates whether this tool should provide support for an interactive mode, in which the tool offers a mode in which the arguments can be provided in a text-driven menu rather than requiring them to be given on the command line. If interactive mode is supported, it may be invoked using the "--interactive" argument. Alternately, if interactive mode is supported and CommandLineTool.defaultsToInteractiveMode() returns true, then interactive mode may be invoked by simply launching the tool without any arguments.
        Overrides:
        supportsInteractiveMode in class CommandLineTool
        Returns:
        true if this tool supports interactive mode, or false if not.
      • 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 class CommandLineTool
        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, or false if not.
      • getExampleUsages

        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 class CommandLineTool
        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.
      • getDirectoryServer

        public InMemoryDirectoryServer getDirectoryServer()
        Retrieves the in-memory directory server instance that has been created by this tool. It will only be valid after the doToolProcessing() method has been called.
        Returns:
        The in-memory directory server instance that has been created by this tool, or null if the directory server instance has not been successfully created.
      • connectionCreationFailure

        public void connectionCreationFailure​(java.net.Socket socket,
                                              java.lang.Throwable cause)
        Indicates that the specified connection is about to be terminated because an unexpected error occurred during processing.
        Specified by:
        connectionCreationFailure in interface LDAPListenerExceptionHandler
        Parameters:
        socket - The socket to be used for the failed connection. It may be null if the failure occurred while attempting to accept the socket rather than attempting to create the client connection from an accepted socket.
        cause - An exception providing additional information about the problem that occurred. It will not be null.