TimeBasedKeys (ModeShape Distribution Library Reference (5.0.0.Final))

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

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.

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

Method Summary

All Methods Static Methods Instance Methods Concrete 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 for which theere is enough space to left shift without overflowing.
    
    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

Class TimeBasedKeys

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_BITS_IN_COUNTER

Constructor Detail

TimeBasedKeys

Method Detail

create

create

nextKey

getCounterStartingAt

getCounterEndingAt

getCounterEndingAfter

getTimeGenerated