Package com.unboundid.util

Class RateAdjustor

java.lang.Object
java.lang.Thread
com.unboundid.util.RateAdjustor
All Implemented Interfaces:
Runnable
@ThreadSafety(level=MOSTLY_THREADSAFE) public final class RateAdjustor extends 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.

  • Field Details

  • Constructor Details

    • RateAdjustor

      public RateAdjustor(@NotNull FixedRateBarrier barrier, long baseRatePerSecond, @NotNull Reader rates) throws IOException, 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:
      IOException - If there is a problem reading from the rates Reader.
      IllegalArgumentException - If there is a problem with the rates input.

  • Method Details

    • newInstance

      @NotNull public static RateAdjustor newInstance(@NotNull FixedRateBarrier barrier, @Nullable Integer baseRatePerSecond, @NotNull File rates) throws IOException, 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:
      IOException - If there is a problem reading from the rates Reader.
      IllegalArgumentException - If there is a problem with the rates input.

    • getVariableRateDataArgumentDescription

      @Nullable public static String getVariableRateDataArgumentDescription(@NotNull 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 String getGenerateSampleVariableRateFileDescription(@NotNull 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 File f) throws IOException
      Writes a sample variable write data file to the specified location.
      Parameters:
      f - The path to the file to be written.
      Throws:
      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 Thread

    • run

      public void run()
      Adjusts the rate in FixedRateBarrier as described in the rates.
      Specified by:
      run in interface Runnable
      Overrides:
      run in class Thread

    • shutDown

      public void shutDown()
      Signals this to shut down.