com.unboundid.util
Class MultiServerLDAPCommandLineTool

java.lang.Object
  extended by com.unboundid.util.CommandLineTool
      extended by com.unboundid.util.MultiServerLDAPCommandLineTool
Direct Known Subclasses:
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:

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
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
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.
 
Methods inherited from class com.unboundid.util.CommandLineTool
createArgumentParser, doShutdownHookProcessing, doToolProcessing, err, getErr, getExampleUsages, getMaxTrailingArguments, getOut, getToolDescription, getToolName, getToolVersion, getTrailingArgumentsPlaceholder, out, registerShutdownHook, runTool, 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(java.io.OutputStream outStream,
                                      java.io.OutputStream errStream,
                                      java.lang.String[] serverNamePrefixes,
                                      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(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.

addNonLDAPArguments

public abstract void addNonLDAPArguments(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.

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

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)
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)
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)
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

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

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

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.