com.unboundid.ldap.sdk.examples
Class SearchAndModRate
java.lang.Object
com.unboundid.util.CommandLineTool
com.unboundid.util.LDAPCommandLineTool
com.unboundid.ldap.sdk.examples.SearchAndModRate
- All Implemented Interfaces:
- java.io.Serializable
@ThreadSafety(level=NOT_THREADSAFE)
public final class SearchAndModRate
- extends LDAPCommandLineTool
- implements java.io.Serializable
This class provides a tool that can be used to search an LDAP directory
server repeatedly using multiple threads, and then modify each entry
returned by that server. It can help provide an estimate of the combined
search and modify performance that a directory server is able to achieve.
Either or both of the base DN and the search filter may be a value pattern as
described in the ValuePattern
class. This makes it possible to
search over a range of entries rather than repeatedly performing searches
with the same base DN and filter.
Some of the APIs demonstrated by this example include:
- Argument Parsing (from the
com.unboundid.util.args
package)
- LDAP Command-Line Tool (from the
com.unboundid.util
package)
- LDAP Communication (from the
com.unboundid.ldap.sdk
package)
- Value Patterns (from the
com.unboundid.util
package)
All of the necessary information is provided using command line arguments.
Supported arguments include those allowed by the LDAPCommandLineTool
class, as well as the following additional arguments:
- "-b {baseDN}" or "--baseDN {baseDN}" -- specifies the base DN to use
for the searches. This must be provided. It may be a simple DN, or it
may be a value pattern to express a range of base DNs.
- "-s {scope}" or "--scope {scope}" -- specifies the scope to use for the
search. The scope value should be one of "base", "one", "sub", or
"subord". If this isn't specified, then a scope of "sub" will be
used.
- "-f {filter}" or "--filter {filter}" -- specifies the filter to use for
the searches. This must be provided. It may be a simple filter, or it
may be a value pattern to express a range of filters.
- "-A {name}" or "--attribute {name}" -- specifies the name of an
attribute that should be included in entries returned from the server.
If this is not provided, then all user attributes will be requested.
This may include special tokens that the server may interpret, like
"1.1" to indicate that no attributes should be returned, "*", for all
user attributes, or "+" for all operational attributes. Multiple
attributes may be requested with multiple instances of this
argument.
- "-m {name}" or "--modifyAttribute {name}" -- specifies the name of the
attribute to modify. Multiple attributes may be modified by providing
multiple instances of this argument. At least one attribute must be
provided.
- "-l {num}" or "--valueLength {num}" -- specifies the length in bytes to
use for the values of the target attributes to modify. If this is not
provided, then a default length of 10 bytes will be used.
- "-C {chars}" or "--characterSet {chars}" -- specifies the set of
characters that will be used to generate the values to use for the
target attributes to modify. It should only include ASCII characters.
Values will be generated from randomly-selected characters from this
set. If this is not provided, then a default set of lowercase
alphabetic characters will be used.
- "-t {num}" or "--numThreads {num}" -- specifies the number of
concurrent threads to use when performing the searches. If this is not
provided, then a default of one thread will be used.
- "-i {sec}" or "--intervalDuration {sec}" -- specifies the length of
time in seconds between lines out output. If this is not provided,
then a default interval duration of five seconds will be used.
- "-I {num}" or "--numIntervals {num}" -- specifies the maximum number of
intervals for which to run. If this is not provided, then it will
run forever.
- "--iterationsBeforeReconnect {num}" -- specifies the number of search
iterations that should be performed on a connection before that
connection is closed and replaced with a newly-established (and
authenticated, if appropriate) connection.
- "-r {ops-per-second}" or "--ratePerSecond {ops-per-second}" --
specifies the target number of operations to perform per second. Each
search and modify operation will be counted separately for this
purpose, so if a value of 1 is specified and a search returns two
entries, then a total of three seconds will be required (one for the
search and one for the modify for each entry). It is still necessary
to specify a sufficient number of threads for achieving this rate. If
this option is not provided, then the tool will run at the maximum rate
for the specified number of threads.
- "--variableRateData {path}" -- specifies the path to a file containing
information needed to allow the tool to vary the target rate over time.
If this option is not provided, then the tool will either use a fixed
target rate as specified by the "--ratePerSecond" argument, or it will
run at the maximum rate.
- "--generateSampleRateFile {path}" -- specifies the path to a file to
which sample data will be written illustrating and describing the
format of the file expected to be used in conjunction with the
"--variableRateData" argument.
- "--warmUpIntervals {num}" -- specifies the number of intervals to
complete before beginning overall statistics collection.
- "--timestampFormat {format}" -- specifies the format to use for
timestamps included before each output line. The format may be one of
"none" (for no timestamps), "with-date" (to include both the date and
the time), or "without-date" (to include only time time).
- "-Y {authzID}" or "--proxyAs {authzID}" -- Use the proxied
authorization v2 control to request that the operations be processed
using an alternate authorization identity. In this case, the bind DN
should be that of a user that has permission to use this control. The
authorization identity may be a value pattern.
- "--suppressErrorResultCodes" -- Indicates that information about the
result codes for failed operations should not be displayed.
- "-c" or "--csv" -- Generate output in CSV format rather than a
display-friendly format.
- See Also:
- Serialized Form
Constructor Summary |
SearchAndModRate(java.io.OutputStream outStream,
java.io.OutputStream errStream)
Creates a new instance of this tool. |
Method Summary |
void |
addNonLDAPArguments(ArgumentParser parser)
Adds the arguments used by this program that aren't already provided by the
generic LDAPCommandLineTool framework. |
ResultCode |
doToolProcessing()
Performs the actual processing for this tool. |
LDAPConnectionOptions |
getConnectionOptions()
Retrieves the connection options that should be used for connections
created for use with 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 the description for this tool. |
java.lang.String |
getToolName()
Retrieves the name for 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 make the appropriate set of
changes. |
static ResultCode |
main(java.lang.String[] args,
java.io.OutputStream outStream,
java.io.OutputStream errStream)
Parse the provided command line arguments and make the appropriate set of
changes. |
void |
stopRunning()
Requests that this tool stop running. |
protected boolean |
supportsMultipleServers()
Indicates whether this tool supports creating connections to multiple
servers. |
Methods inherited from class com.unboundid.util.LDAPCommandLineTool |
addToolArguments, createBindRequest, createServerSet, createSSLUtil, createSSLUtil, doExtendedArgumentValidation, doExtendedNonLDAPArgumentValidation, getBindControls, getConnection, getConnectionPool, getUnauthenticatedConnection, supportsAuthentication |
Methods inherited from class com.unboundid.util.CommandLineTool |
createArgumentParser, doShutdownHookProcessing, err, getErr, getMaxTrailingArguments, getOut, getTrailingArgumentsPlaceholder, out, registerShutdownHook, runTool, wrapErr, wrapOut |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
SearchAndModRate
public SearchAndModRate(java.io.OutputStream outStream,
java.io.OutputStream errStream)
- Creates a new instance of this tool.
- 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.
main
public static void main(java.lang.String[] args)
- Parse the provided command line arguments and make the appropriate set of
changes.
- Parameters:
args
- The command line arguments provided to this program.
main
public static ResultCode main(java.lang.String[] args,
java.io.OutputStream outStream,
java.io.OutputStream errStream)
- Parse the provided command line arguments and make the appropriate set of
changes.
- Parameters:
args
- The command line arguments provided to this program.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.
- Returns:
- A result code indicating whether the processing was successful.
getToolName
public java.lang.String getToolName()
- Retrieves the name for this tool.
- Specified by:
getToolName
in class CommandLineTool
- Returns:
- The name for this tool.
getToolDescription
public java.lang.String getToolDescription()
- Retrieves the description for this tool.
- Specified by:
getToolDescription
in class CommandLineTool
- Returns:
- The description for this tool.
getToolVersion
public java.lang.String getToolVersion()
- Retrieves the version string for this tool.
- Overrides:
getToolVersion
in class CommandLineTool
- Returns:
- The version string for this tool.
addNonLDAPArguments
public void addNonLDAPArguments(ArgumentParser parser)
throws ArgumentException
- Adds the arguments used by this program that aren't already provided by the
generic
LDAPCommandLineTool
framework.
- Specified by:
addNonLDAPArguments
in class LDAPCommandLineTool
- Parameters:
parser
- The argument parser to which the arguments should be added.
- Throws:
ArgumentException
- If a problem occurs while adding the arguments.
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.
- Overrides:
supportsMultipleServers
in class LDAPCommandLineTool
- Returns:
true
if this tool supports creating connections to
multiple servers, or false
if not.
getConnectionOptions
public LDAPConnectionOptions getConnectionOptions()
- Retrieves the connection options that should be used for connections
created for use with this tool.
- Overrides:
getConnectionOptions
in class LDAPCommandLineTool
- Returns:
- The connection options that should be used for connections created
for use with this tool.
doToolProcessing
public ResultCode doToolProcessing()
- Performs the actual processing for this tool. In this case, it gets a
connection to the directory server and uses it to perform the requested
searches.
- Specified by:
doToolProcessing
in class CommandLineTool
- Returns:
- The result code for the processing that was performed.
stopRunning
public void stopRunning()
- Requests that this tool stop running. This method will attempt to wait
for all threads to complete before returning control to the caller.
getExampleUsages
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.