com.unboundid.util

Class RateAdjustor

java.lang.Object

java.lang.Thread

com.unboundid.util.RateAdjustor

All Implemented Interfaces:

java.lang.Runnable

@ThreadSafety(level=MOSTLY_THREADSAFE)
public final class RateAdjustor
extends java.lang.Thread

This class allows a FixedRateBarrier to change dynamically. The rate changes are governed by lines read from a Reader (typically backed by a file). The input starts with a header that provides some global options and then has a list of lines, where each line contains a single rate per second, a comma, and a duration to maintain that rate. Rates are specified as an absolute rate per second or as a rate relative to the base rate per second. The duration is an integer followed by a time unit (ms=milliseconds, s=seconds, m=minutes, h=hours, and d=days).

The following simple example will run at a target rate of 1000 per second for one minute, and then 10000 per second for 10 seconds.

   # format=rate-duration
   1000,1m
   10000,10s
 

The following example has a default duration of one minute, and will repeat the two intervals until this RateAdjustor is shut down. The first interval is run for the default of 1 minute at two and half times the base rate, and then run for 10 seconds at 10000 per second.

   # format=rate-duration
   # default-duration=1m
   # repeat=true
   2.5X
   10000,10s
 

A RateAdjustor is a daemon thread. It is necessary to call the start() method to start the thread and begin the rate changes. Once this finished processing the rates, the thread will complete. It can be stopped prematurely by calling shutDown().

The header can contain the following options:

• format (required): This must currently have the value rate-duration.
• default-duration (optional): This can specify a default duration for intervals that do not include a duration. The format is an integer followed by a time unit as described above.
• repeat (optional): If this has a value of true, then the rates in the input will be repeated until shutDown() is called.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
static char	COMMENT_START This starts a comment in the input.
static java.lang.String	DEFAULT_DURATION_KEY The header key that represents the default duration.
static java.lang.String	END_HEADER_TEXT The text that must appear on a line by itself in order to denote that the end of the file header has been reached.
static java.lang.String	FORMAT_KEY The header key that represents the format of the file.
static java.lang.String	FORMAT_VALUE_RATE_DURATION The value of the format key that represents a list of rates and durations within the input file.
static java.util.List<java.lang.String>	FORMATS A list of all formats that we support.
static java.util.List<java.lang.String>	KEYS A list of all header keys that we support.
static java.lang.String	REPEAT_KEY The header key that represents whether the input should be repeated.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
RateAdjustor(FixedRateBarrier barrier, long baseRatePerSecond, java.io.Reader rates) Constructs a new RateAdjustor with the specified parameters.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	getGenerateSampleVariableRateFileDescription(java.lang.String dataFileArgName) Retrieves a string that may be used as the description of the argument that generates a sample variable rate data file that serves as documentation of the variable rate data format.
static java.lang.String	getVariableRateDataArgumentDescription(java.lang.String genArgName) Retrieves a string that may be used as the description of the argument that specifies the path to a variable rate data file for use in conjunction with this rate adjustor.
static RateAdjustor	newInstance(FixedRateBarrier barrier, java.lang.Integer baseRatePerSecond, java.io.File rates) Returns a new RateAdjustor with the specified parameters.
void	run() Adjusts the rate in FixedRateBarrier as described in the rates.
void	shutDown() Signals this to shut down.
void	start() Starts this thread and waits for the initial rate to be set.
static void	writeSampleVariableRateFile(java.io.File f) Writes a sample variable write data file to the specified location.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

COMMENT_START

public static final char COMMENT_START

This starts a comment in the input.

See Also:

Constant Field Values

END_HEADER_TEXT

@NotNull
public static final java.lang.String END_HEADER_TEXT

The text that must appear on a line by itself in order to denote that the end of the file header has been reached.

See Also:

Constant Field Values

DEFAULT_DURATION_KEY

@NotNull
public static final java.lang.String DEFAULT_DURATION_KEY

The header key that represents the default duration.

See Also:

Constant Field Values

FORMAT_KEY

@NotNull
public static final java.lang.String FORMAT_KEY

The header key that represents the format of the file.

See Also:

Constant Field Values

FORMAT_VALUE_RATE_DURATION

@NotNull
public static final java.lang.String FORMAT_VALUE_RATE_DURATION

The value of the format key that represents a list of rates and durations within the input file.

See Also:

Constant Field Values

FORMATS

@NotNull
public static final java.util.List<java.lang.String> FORMATS

A list of all formats that we support.

REPEAT_KEY

@NotNull
public static final java.lang.String REPEAT_KEY

The header key that represents whether the input should be repeated.

See Also:

Constant Field Values

KEYS

@NotNull
public static final java.util.List<java.lang.String> KEYS

A list of all header keys that we support.

Constructor Detail

RateAdjustor

public RateAdjustor(@NotNull
                    FixedRateBarrier barrier,
                    long baseRatePerSecond,
                    @NotNull
                    java.io.Reader rates)
             throws java.io.IOException,
                    java.lang.IllegalArgumentException

Constructs a new RateAdjustor with the specified parameters. See the class-level javadoc for more information.

Parameters:

barrier - The barrier to update based on the specified rates.

baseRatePerSecond - The baseline rate per second, or 0 if none was specified.

rates - A list of rates and durations as described in the class-level javadoc. The reader will always be closed before this method returns.

Throws:

java.io.IOException - If there is a problem reading from the rates Reader.

java.lang.IllegalArgumentException - If there is a problem with the rates input.

Method Detail

newInstance

@NotNull
public static RateAdjustor newInstance(@NotNull
                                                FixedRateBarrier barrier,
                                                @Nullable
                                                java.lang.Integer baseRatePerSecond,
                                                @NotNull
                                                java.io.File rates)
                                         throws java.io.IOException,
                                                java.lang.IllegalArgumentException

Returns a new RateAdjustor with the specified parameters. See the class-level javadoc for more information.

Parameters:

barrier - The barrier to update based on the specified rates.

baseRatePerSecond - The baseline rate per second, or null if none was specified.

rates - A file containing a list of rates and durations as described in the class-level javadoc.

Returns:

A new RateAdjustor constructed from the specified parameters.

Throws:

java.io.IOException - If there is a problem reading from the rates Reader.

java.lang.IllegalArgumentException - If there is a problem with the rates input.

getVariableRateDataArgumentDescription

@Nullable
public static java.lang.String getVariableRateDataArgumentDescription(@NotNull
                                                                                java.lang.String genArgName)

Retrieves a string that may be used as the description of the argument that specifies the path to a variable rate data file for use in conjunction with this rate adjustor.

Parameters:

genArgName - The name of the argument that may be used to generate a sample variable rate data file.

Returns:

A string that may be used as the description of the argument that specifies the path to a variable rate data file for use in conjunction with this rate adjustor.

getGenerateSampleVariableRateFileDescription

@Nullable
public static java.lang.String getGenerateSampleVariableRateFileDescription(@NotNull
                                                                                      java.lang.String dataFileArgName)

Retrieves a string that may be used as the description of the argument that generates a sample variable rate data file that serves as documentation of the variable rate data format.

Parameters:

dataFileArgName - The name of the argument that specifies the path to a file

Returns:

A string that may be used as the description of the argument that generates a sample variable rate data file that serves as documentation of the variable rate data format.

writeSampleVariableRateFile

public static void writeSampleVariableRateFile(@NotNull
                                               java.io.File f)
                                        throws java.io.IOException

Writes a sample variable write data file to the specified location.

Parameters:

f - The path to the file to be written.

Throws:

java.io.IOException - If a problem is encountered while writing to the specified file.

start

public void start()

Starts this thread and waits for the initial rate to be set.

Overrides:

start in class java.lang.Thread

run

public void run()

Adjusts the rate in FixedRateBarrier as described in the rates.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

shutDown

public void shutDown()

Signals this to shut down.