Package 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.
-
-
Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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
-
-
-
-
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 beSystem.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 beSystem.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 benull
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 benull
if only prefixes should be used.- Throws:
LDAPSDKUsageException
- If both the sets of server name prefixes and suffixes arenull
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 classCommandLineTool
- 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, orfalse
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 theCommandLineTool.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 classCommandLineTool
- 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 theCommandLineTool.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 theCommandLineTool.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 theCommandLineTool.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 theCommandLineTool.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.
-
-