com.unboundid.util
Class RateAdjustor

java.lang.Object
  extended by java.lang.Thread
      extended by 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:


Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
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
RateAdjustor(FixedRateBarrier barrier, long baseRatePerSecond, java.io.Reader rates)
          Constructs a new RateAdjustor with the specified parameters.
 
Method Summary
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

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

public static final java.lang.String DEFAULT_DURATION_KEY
The header key that represents the default duration.

See Also:
Constant Field Values

FORMAT_KEY

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

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

public static final java.util.List<java.lang.String> FORMATS
A list of all formats that we support.


REPEAT_KEY

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

public static final java.util.List<java.lang.String> KEYS
A list of all header keys that we support.

Constructor Detail

RateAdjustor

public RateAdjustor(FixedRateBarrier barrier,
                    long baseRatePerSecond,
                    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

public static RateAdjustor newInstance(FixedRateBarrier barrier,
                                       java.lang.Integer baseRatePerSecond,
                                       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

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

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

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

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