Package io.permazen.kv.raft

Class Timestamp

java.lang.Object

io.permazen.kv.raft.Timestamp

All Implemented Interfaces:

Comparable<Timestamp>

public class Timestamp
extends Object
implements Comparable<Timestamp>

Represents a relative timestamp in milliseconds.

Values are stored as an unsigned 32 bit integer, which therefore recycles after 2³² milliseconds (about 48 days). Two values to be compared must have been generated within 24 days of each other to be ordered correctly.

This class uses System.nanoTime(), not System.currentTimeMillis(), and so is immune to changes in the system clock. To facilitate debugging, the zero mark is set at class initialization time.

Instances are immutable.

Field Summary

Fields

Modifier and Type	Field	Description
static final Comparator<Timestamp>	NULL_FIRST_SORT	Sorts possibly null Timestamps in chronological order, with null sorting first.

Constructor Summary

Constructors

Constructor	Description
Timestamp()	Constructor returning the current time.
Timestamp(int millis)	Constructor.

Method Summary

Modifier and Type	Method	Description
int	compareTo(Timestamp that)	Compare two instances, where "smaller" means earlier in time.
boolean	equals(Object obj)
int	getMillis()	Get the relative milliseconds value contained by this instance.
int	hashCode()
boolean	hasOccurred()	Determine whether this timestamp is in the past or the future.
boolean	isRolloverDanger()	Determine whether this timestamp is so far in the past that it is in danger of rolling over to the future as time continues to move forward.
Timestamp	offset(int offset)	Return this timestamp offset by the given amount.
int	offsetFrom(Timestamp base)	Get the number of milliseconds this instance is offset from the given instance.
int	offsetFromNow()	Get the number of milliseconds this instance is offset from the current time.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

NULL_FIRST_SORT

public static final Comparator<Timestamp> NULL_FIRST_SORT

Sorts possibly null Timestamps in chronological order, with null sorting first.

All non-null Timestamps must be contained within a single 2³¹-1 range; otherwise results are undefined.

Constructor Details

Timestamp

public Timestamp()

Constructor returning the current time.

Timestamp

public Timestamp(int millis)

Constructor.

Parameters:

millis - relative milliseconds value from getMillis()

Method Details

getMillis

public int getMillis()

Get the relative milliseconds value contained by this instance.

Returns:

relative millisecond value

offsetFromNow

public int offsetFromNow()

Get the number of milliseconds this instance is offset from the current time.

A positive offset means this instance is in the future.

Returns:

relative millisecond offset

offsetFrom

public int offsetFrom(Timestamp base)

Get the number of milliseconds this instance is offset from the given instance.

A positive offset means this instance is after base.

Parameters:

base - base timestamp

Returns:

relative millisecond offset

Throws:

IllegalArgumentException - if base is null

offset

public Timestamp offset(int offset)

Return this timestamp offset by the given amount.

Parameters:

offset - offset in milliseconds

Returns:

adjusted timestamp

hasOccurred

public boolean hasOccurred()

Determine whether this timestamp is in the past or the future.

Returns:

true if this timestamp is in the past

isRolloverDanger

public boolean isRolloverDanger()

Determine whether this timestamp is so far in the past that it is in danger of rolling over to the future as time continues to move forward.

This returns true if this timestamp is within 5% of the roll-over point relative to the current time. This would represent a time approximately 22.8 days in the past.

Returns:

true if this timestamp's offset is dangerously negative

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

compareTo

public int compareTo(Timestamp that)

Compare two instances, where "smaller" means earlier in time.

Note: because timestamps recycle every 48 days, this method does not totally order instances.

Specified by:

compareTo in interface Comparable<Timestamp>

Parameters:

that - timestamp to compare with

Throws:

IllegalArgumentException - if this instance and that differ by exactly 2³¹ milliseconds

NullPointerException - if that is null