com.unboundid.util

Class MultiServerLDAPCommandLineTool

java.lang.Object

com.unboundid.util.CommandLineTool

com.unboundid.util.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 Summary

Constructors

Constructor and Description
MultiServerLDAPCommandLineTool(java.io.OutputStream outStream, java.io.OutputStream errStream, java.lang.String[] serverNamePrefixes, java.lang.String[] serverNameSuffixes) Creates a new instance of this multi-server LDAP command-line tool.

Method Summary

Methods

Modifier and Type	Method and 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.
BindRequest	createBindRequest(int serverIndex) Creates the bind request to use to authenticate to the indicated server.
ServerSet	createServerSet(int serverIndex) Creates the server set to use when creating connections or connection pools.
SSLUtil	createSSLUtil(int serverIndex) Creates the SSLUtil instance to use for secure communication.
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.
LDAPConnection	getConnection(int serverIndex) Retrieves a connection that may be used to communicate with the indicated 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 serverIndex, int initialConnections, int maxConnections) Retrieves a connection pool that may be used to communicate with the indicated directory server.
LDAPConnection	getUnauthenticatedConnection(int serverIndex) Retrieves an unauthenticated connection that may be used to communicate with the indicated 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.

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

Methods inherited from class java.lang.Object

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

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.