com.unboundid.ldap.listener

Class InMemoryDirectoryServerTool

java.lang.Object

com.unboundid.util.CommandLineTool

com.unboundid.ldap.listener.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 enforce schema compliance.
• "-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 enforce schema compliance. 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.
• "--doNotValidateSchemaDefinitions" -- indicates that the server should not perform any validation for the custom schema provided using the --useSchemaFile argument. If this argument is not used and a custom schema is configured, then the server will validate that schema and report errors or warnings for any issues that it identifies with that schema.
• "--doNotGenerateOperationalAttributes" -- indicates that the server should not maintain any operational attributes (including entryDN, entryUUID, subschemaSubentry, creatorsName, createTimestamp, modifiersName, and modifyTimestamp) in entries.
• "-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 return 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 Summary

Constructors

Constructor and Description
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.

Method Summary

Modifier and Type	Method and Description
void	addToolArguments(ArgumentParser parser) Adds the command-line arguments supported for use with this tool to the provided argument parser.
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.
void	connectionTerminated(LDAPListenerClientConnection connection, LDAPException cause) Indicates that the specified connection is about to be terminated because an unexpected error occurred during processing.
boolean	defaultsToInteractiveMode() Indicates whether this tool defaults to launching in interactive mode if the tool is invoked without any command-line arguments.
ResultCode	doToolProcessing() Performs the core set of processing for this tool.
InMemoryDirectoryServer	getDirectoryServer() Retrieves the in-memory directory server instance that has been created by this tool.
java.util.LinkedHashMap<java.lang.String[],java.lang.String>	getExampleUsages() Retrieves a set of information that may be used to generate example usage information.
java.lang.String	getToolDescription() Retrieves a human-readable description for this tool.
java.lang.String	getToolName() Retrieves the name of this tool.
java.lang.String	getToolVersion() Retrieves the version string for this tool.
static void	main(java.lang.String... args) Parse the provided command line arguments and uses them to start the directory server.
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.
protected boolean	supportsDebugLogging() Indicates whether this tool supports the ability to generate a debug log file.
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.
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.

Methods inherited from class com.unboundid.util.CommandLineTool

addEnableSSLDebuggingArgument, createArgumentParser, doExtendedArgumentValidation, doShutdownHookProcessing, err, getAdditionalDescriptionParagraphs, getErr, getMaxTrailingArguments, getMinTrailingArguments, getOriginalErr, getOriginalOut, getOut, getPasswordFileReader, getToolCompletionMessage, getTrailingArgumentsPlaceholder, logToolInvocationByDefault, out, registerShutdownHook, requestToolArgumentsInteractively, runTool, supportsOutputFile, wrapErr, wrapOut

Methods inherited from class java.lang.Object

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

Constructor Detail

InMemoryDirectoryServerTool

public InMemoryDirectoryServerTool(@Nullable
                                   java.io.OutputStream outStream,
                                   @Nullable
                                   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(@NotNull
                        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

@NotNull
public static ResultCode main(@NotNull
                                       java.lang.String[] args,
                                       @Nullable
                                       java.io.OutputStream outStream,
                                       @Nullable
                                       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

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

getToolDescription

@NotNull
public java.lang.String getToolDescription()

Retrieves a human-readable description for this tool. If the description should include multiple paragraphs, then this method should return the text for the first paragraph, and the CommandLineTool.getAdditionalDescriptionParagraphs() method should be used to return the text for the subsequent paragraphs.

Specified by:

getToolDescription in class CommandLineTool

Returns:

A human-readable description for this tool.

getToolVersion

@NotNull
public java.lang.String getToolVersion()

Retrieves the version string for this tool.

Overrides:

getToolVersion in class CommandLineTool

Returns:

The version string for this tool.

addToolArguments

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

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.

defaultsToInteractiveMode

public boolean defaultsToInteractiveMode()

Indicates whether this tool defaults to launching in interactive mode if the tool is invoked without any command-line arguments. This will only be used if CommandLineTool.supportsInteractiveMode() returns true.

Overrides:

defaultsToInteractiveMode in class CommandLineTool

Returns:

true if this tool defaults to using interactive mode if launched without any command-line arguments, 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.

supportsDebugLogging

protected boolean supportsDebugLogging()

Indicates whether this tool supports the ability to generate a debug log file. If this method returns true, then the tool will expose additional arguments that can control debug logging.

Overrides:

supportsDebugLogging in class CommandLineTool

Returns:

true if this tool supports the ability to generate a debug log file, or false if not.

doToolProcessing

@NotNull
public ResultCode doToolProcessing()

Performs the core set of processing for this tool.

Specified by:

doToolProcessing in class CommandLineTool

Returns:

A result code that indicates whether the processing completed successfully.

getExampleUsages

@NotNull
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

@Nullable
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(@Nullable
                                      java.net.Socket socket,
                                      @NotNull
                                      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.

connectionTerminated

public void connectionTerminated(@NotNull
                                 LDAPListenerClientConnection connection,
                                 @NotNull
                                 LDAPException cause)

Indicates that the specified connection is about to be terminated because an unexpected error occurred during processing.

Specified by:

connectionTerminated in interface LDAPListenerExceptionHandler

Parameters:

connection - The connection that will be terminated. It will not be null.

cause - An exception providing additional information about the reason for the termination. It will not be null.