org.modeshape.common.util

## Class TimeBasedKeys

- java.lang.Object
- - org.modeshape.common.util.TimeBasedKeys

-     @ThreadSafe
      public final class TimeBasedKeys
      extends Object

  This is a generator of simple unique and (non-monotonically) increasing long-value keys that incorporate the time in which they were generated. A single generator instance will never return two identical keys, and all keys are unique and naturally sorted in time. The generator is safe to be called concurrently from multiple threads.

  Each long key value contains the time (in milliseconds) at which the key is generated, left-shifted by 16 bits. Those 16 bits are then used to store a counter value that is unique for each millisecond. When a new key is needed, the current time is compared to the last time for which a key was generated. If the times are different, then the counter is reset to 0; otherwise, the counter is incremented.

  Use a single generator instance for each sequence of keys.

  To obtain a unique value, simply call:

       TimeBasedKeys keys = TimeBasedKeys.create();
       ...
       long key = keys.nextKey();

  Because the keys are time-based, the geneartor can also identify the range of keys that were created before or after a given instant in time, or within a range of times. For example, all keys obtained after January 10, 2014 at 12:12:41.845-06:00 (which has a `System.currentTimeMillis()` value of `1389378406`) will be greater than or equal to the following value:

       long timeInMillis = 1389378406L;
       long minKey = keys.getKeyStartingAt(timeInMillis);

  Using this and similar methods, one can obtain all counter values that might have been generated, for example, sometime during 2012:

       long janFirst2012 = 1325397600L; // Jan 1 2012 at 00:00.000 UTC
       long janFirst2013 = 1357020000L; // Jan 1 2013 at 00:00.000 UTC
       long smallestKey = keys.getKeyStartingAt(janFirst2012);
       long justLargerKey = keys.getKeyStartingAt(janFirst2013);

  Then all keys generated during 2012 will therefore satisfy:

       smallestKey >= key && key < justLargerKey

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static short` | `DEFAULT_BITS_IN_COUNTER` By default each `TimeBasedKeys` instance will use 16 bits for the counter.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TimeBasedKeys(short bitsUsedInCounter)` Create a new key generator.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TimeBasedKeys` | `create()` Create a new generator that uses 16 bits for the counter portion of the keys.
    `static TimeBasedKeys` | `create(int bitsUsedInCounter)` Create a new generator that uses the specified number of bits for the counter portion of the keys.
    `long` | `getCounterEndingAfter(long millisInUtc)` Obtain the first (earliest) key that would have been generated after the specified UTC time.
    `long` | `getCounterEndingAt(long millisInUtc)` Obtain the largest (latest) key that would have been generated at the specified UTC time.
    `long` | `getCounterStartingAt(long millisInUtc)` Obtain the first (earliest) key that would have been generated at the specified UTC time.
    `long` | `getTimeGenerated(long key)` Obtain the milliseconds since epoch in UTC that the supplied key was generated.
    `long` | `nextKey()` Get the next key for the current time in UTC.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_BITS_IN_COUNTER

          public static final short DEFAULT_BITS_IN_COUNTER

      By default each `TimeBasedKeys` instance will use 16 bits for the counter. That results in a maximum of of 65535 distinct values per millisecond (which is likely sufficient), while also leaving enough bits in the long to store a value well past the year 10,000.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TimeBasedKeys

          protected TimeBasedKeys(short bitsUsedInCounter)

      Create a new key generator.
      Parameters:
        `bitsUsedInCounter` - the number of bits to be used in the counter.

  - ### Method Detail

    - #### create

          public static TimeBasedKeys create()

      Create a new generator that uses 16 bits for the counter portion of the keys.
      Returns:
        the generator instance; never null

    - #### create

          public static TimeBasedKeys create(int bitsUsedInCounter)

      Create a new generator that uses the specified number of bits for the counter portion of the keys.
      Parameters:
        `bitsUsedInCounter` - the number of bits in the counter portion of the keys; must be a positive number between 1 and 32.
      Returns:
        the generator instance; never null

    - #### nextKey

          public long nextKey()

      Get the next key for the current time in UTC.
      Returns:
        a long that is determined by the current time in UTC and a unique counter value for the current time.

    - #### getCounterStartingAt

          public long getCounterStartingAt(long millisInUtc)

      Obtain the first (earliest) key that would have been generated at the specified UTC time. The resulting key is equal to or smaller than all keys generated at or since that time.
      Parameters:
        `millisInUtc` - the number of milliseconds (in UTC) past epoch, and the time at which `nextKey()` might have been called
      Returns:
        a long value that is the earliest possible key for the given time

    - #### getCounterEndingAt

          public long getCounterEndingAt(long millisInUtc)

      Obtain the largest (latest) key that would have been generated at the specified UTC time. The resulting key is equal to or greater than all keys generated at or before that time.
      Parameters:
        `millisInUtc` - the number of milliseconds (in UTC) past epoch, and the time at which `nextKey()` might have been called
      Returns:
        a long value that is the latest possible key for the given time

    - #### getCounterEndingAfter

          public long getCounterEndingAfter(long millisInUtc)

      Obtain the first (earliest) key that would have been generated after the specified UTC time. The resulting key is greater than all keys generated at or before that time.
      Parameters:
        `millisInUtc` - the number of milliseconds (in UTC) past epoch, and the time at which `nextKey()` might have been called
      Returns:
        a long value that is the latest possible key for the given time

    - #### getTimeGenerated

          public long getTimeGenerated(long key)

      Obtain the milliseconds since epoch in UTC that the supplied key was generated. The value is the same value that would have been returned by `System.currentTimeMillis()` when the key was generated.
      Parameters:
        `key` - the key
      Returns:
        the generated time, in millseconds past epoch

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.