com.unboundid.util
Class LDAPCommandLineTool

java.lang.Object
  extended by com.unboundid.util.CommandLineTool
      extended by com.unboundid.util.LDAPCommandLineTool
Direct Known Subclasses:
AuthRate, GenerateSourceFromSchema, IdentifyReferencesToMissingEntries, IdentifyUniqueAttributeConflicts, LDAPCompare, LDAPDebugger, LDAPModify, LDAPSearch, ModRate, SearchAndModRate, SearchRate, ValidateLDIF

@Extensible
@ThreadSafety(level=INTERFACE_NOT_THREADSAFE)
public abstract class LDAPCommandLineTool
extends CommandLineTool

This class provides a basis for developing command-line tools that communicate with an LDAP directory server. It provides a common set of options for connecting and authenticating to a directory server, and then provides a mechanism for obtaining connections and connection pools to use when communicating with that server.

The arguments that 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 (e.g., "--saslOption mech=EXTERNAL" indicates that the EXTERNAL mechanism should be used). Depending on the SASL mechanism, additional SASL options may be required or optional. They include:

Note that in general, methods in this class are not threadsafe. However, the getConnection() and getConnectionPool(int,int) methods may be invoked concurrently by multiple threads accessing the same instance only while that instance is in the process of invoking the CommandLineTool.doToolProcessing() method.


Constructor Summary
LDAPCommandLineTool(java.io.OutputStream outStream, java.io.OutputStream errStream)
          Creates a new instance of this LDAP-enabled command-line tool with the provided information.
 
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()
          Creates the bind request to use to authenticate to the server.
 ServerSet createServerSet()
          Creates the server set to use when creating connections or connection pools.
 SSLUtil createSSLUtil()
          Creates the SSLUtil instance to use for secure communication.
 SSLUtil createSSLUtil(boolean force)
          Creates the SSLUtil instance to use for secure communication.
protected  boolean defaultToPromptForBindPassword()
          Indicates whether this tool should default to interactively prompting for the bind password if a password is required but no argument was provided to indicate how to get the password.
 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.
protected  java.util.List<Control> getBindControls()
          Retrieves a set of controls that should be included in any bind request generated by this tool.
 LDAPConnection getConnection()
          Retrieves a connection that may be used to communicate with the target 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 initialConnections, int maxConnections)
          Retrieves a connection pool that may be used to communicate with the target directory server.
 LDAPConnectionPool getConnectionPool(int initialConnections, int maxConnections, int initialConnectThreads, PostConnectProcessor beforeStartTLSProcessor, PostConnectProcessor afterStartTLSProcessor, boolean throwOnConnectFailure, LDAPConnectionPoolHealthCheck healthCheck)
          Retrieves a connection pool that may be used to communicate with the target directory server.
 LDAPConnection getUnauthenticatedConnection()
          Retrieves an unauthenticated connection that may be used to communicate with the target 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.
protected  boolean supportsAuthentication()
          Indicates whether this tool should provide the arguments that allow it to bind via simple or SASL authentication.
protected  boolean supportsMultipleServers()
          Indicates whether this tool supports creating connections to multiple servers.
protected  boolean supportsSASLHelp()
          Indicates whether this tool should provide a "--help-sasl" argument that provides information about the supported SASL mechanisms and their associated properties.
 
Methods inherited from class com.unboundid.util.CommandLineTool
createArgumentParser, defaultsToInteractiveMode, doShutdownHookProcessing, doToolProcessing, err, getErr, getExampleUsages, getMaxTrailingArguments, getMinTrailingArguments, getOriginalErr, getOriginalOut, getOut, getToolDescription, getToolName, getToolVersion, getTrailingArgumentsPlaceholder, out, registerShutdownHook, 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

LDAPCommandLineTool

public LDAPCommandLineTool(java.io.OutputStream outStream,
                           java.io.OutputStream errStream)
Creates a new instance of this LDAP-enabled command-line tool with the provided information.

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

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

supportsAuthentication

protected boolean supportsAuthentication()
Indicates whether this tool should provide the arguments that allow it to bind via simple or SASL authentication.

Returns:
true if this tool should provide the arguments that allow it to bind via simple or SASL authentication, or false if not.

defaultToPromptForBindPassword

protected boolean defaultToPromptForBindPassword()
Indicates whether this tool should default to interactively prompting for the bind password if a password is required but no argument was provided to indicate how to get the password.

Returns:
true if this tool should default to interactively prompting for the bind password, or false if not.

supportsSASLHelp

protected boolean supportsSASLHelp()
Indicates whether this tool should provide a "--help-sasl" argument that provides information about the supported SASL mechanisms and their associated properties.

Returns:
true if this tool should provide a "--help-sasl" argument, or false if not.

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.

getBindControls

protected java.util.List<Control> getBindControls()
Retrieves a set of controls that should be included in any bind request generated by this tool.

Returns:
A set of controls that should be included in any bind request generated by this tool. It may be null or empty if no controls should be included in the bind request.

supportsMultipleServers

protected boolean supportsMultipleServers()
Indicates whether this tool supports creating connections to multiple servers. If it is to support multiple servers, then the "--hostname" and "--port" arguments will be allowed to be provided multiple times, and will be required to be provided the same number of times. The same type of communication security and bind credentials will be used for all servers.

Returns:
true if this tool supports creating connections to multiple servers, or false if not.

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()
                                   throws LDAPException
Retrieves a connection that may be used to communicate with the target 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.

Returns:
A connection that may be used to communicate with the target directory server.
Throws:
LDAPException - If a problem occurs while creating the connection.

getUnauthenticatedConnection

@ThreadSafety(level=METHOD_THREADSAFE)
public final LDAPConnection getUnauthenticatedConnection()
                                                  throws LDAPException
Retrieves an unauthenticated connection that may be used to communicate with the target 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.

Returns:
An unauthenticated connection that may be used to communicate with the target directory server.
Throws:
LDAPException - If a problem occurs while creating the connection.

getConnectionPool

@ThreadSafety(level=METHOD_THREADSAFE)
public final LDAPConnectionPool getConnectionPool(int initialConnections,
                                                                                     int maxConnections)
                                           throws LDAPException
Retrieves a connection pool that may be used to communicate with the target 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:
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 target directory server.
Throws:
LDAPException - If a problem occurs while creating the connection pool.

getConnectionPool

@ThreadSafety(level=METHOD_THREADSAFE)
public final LDAPConnectionPool getConnectionPool(int initialConnections,
                                                                                     int maxConnections,
                                                                                     int initialConnectThreads,
                                                                                     PostConnectProcessor beforeStartTLSProcessor,
                                                                                     PostConnectProcessor afterStartTLSProcessor,
                                                                                     boolean throwOnConnectFailure,
                                                                                     LDAPConnectionPoolHealthCheck healthCheck)
                                           throws LDAPException
Retrieves a connection pool that may be used to communicate with the target 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:
initialConnections - The number of connections that should be initially established in the pool.
maxConnections - The maximum number of connections to maintain in the pool.
initialConnectThreads - The number of concurrent threads to use to establish the initial set of connections. A value greater than one indicates that the attempt to establish connections should be parallelized.
beforeStartTLSProcessor - An optional post-connect processor that should be used for the connection pool and should be invoked before any StartTLS post-connect processor that may be needed based on the selected arguments. It may be null if no such post-connect processor is needed.
afterStartTLSProcessor - An optional post-connect processor that should be used for the connection pool and should be invoked after any StartTLS post-connect processor that may be needed based on the selected arguments. It may be null if no such post-connect processor is needed.
throwOnConnectFailure - If an exception should be thrown if a problem is encountered while attempting to create the specified initial number of connections. If true, then the attempt to create the pool will fail if any connection cannot be established. If false, then the pool will be created but may have fewer than the initial number of connections (or possibly no connections).
healthCheck - An optional health check that should be configured for the connection pool. It may be null if the default health checking should be performed.
Returns:
A connection that may be used to communicate with the target directory server.
Throws:
LDAPException - If a problem occurs while creating the connection pool.

createServerSet

public ServerSet createServerSet()
                          throws LDAPException
Creates the server set to use when creating connections or connection pools.

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 SSLUtil createSSLUtil()
                      throws LDAPException
Creates the SSLUtil instance to use for secure communication.

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.

createSSLUtil

public SSLUtil createSSLUtil(boolean force)
                      throws LDAPException
Creates the SSLUtil instance to use for secure communication.

Parameters:
force - Indicates whether to create the SSLUtil object even if neither the "--useSSL" nor the "--useStartTLS" argument was provided. The key store and/or trust store paths must still have been provided. This may be useful for tools that accept SSL-based communication but do not themselves intend to perform SSL-based communication as an LDAP client.
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 BindRequest createBindRequest()
                              throws LDAPException
Creates the bind request to use to authenticate to the server.

Returns:
The bind request to use to authenticate to the server, or null if no bind should be performed.
Throws:
LDAPException - If a problem occurs while creating the bind request.