Class 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 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 Description
      RateAdjustor​(FixedRateBarrier barrier, long baseRatePerSecond, java.io.Reader rates)
      Constructs a new RateAdjustor with the specified parameters.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, onSpinWait, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, stop, suspend, toString, yield
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

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