@Immutable public final class DateTime extends Object implements Serializable, Comparable<DateTime>
Implements a date and time object based on the Modified Julian Date (introduced by the Smithsonian Astrophysical Observatory in 1957). Its internal representation is a 64 bits integer (long) holding the number of 100 nanoseconds since 1858-11-17 00:00 UTC.
That representation has been chosen to simplify time manipulations in a timed events database. The fondness of the author for OpenVMS may also have something to do with it.
This implementation uses negative values to represent times before 1858-11-17 00:00 UTC. The years before 1 A.D. are numbered according to astronomical conventions: e.g. 2 B.C is formatted as -0001. This allows the representation of times from 12754 B.C. to 16472 A.D.
The limits have been set to half the possible range to avoid an elapsed time overflow when subtracting two time values.
Modifier and Type | Class and Description |
---|---|
static class |
DateTime.Context
Context.
|
static class |
DateTime.Fields
Fields.
|
Modifier and Type | Field and Description |
---|---|
static DateTime |
BEGINNING_OF_TIME
Beginning of time.
|
static String |
BEGINNING_OF_TIME_STRING
Beginning of time string.
|
static DateTime |
END_OF_TIME
End of time.
|
static String |
END_OF_TIME_STRING
End of time string.
|
static int |
FILE_NAME_LENGTH
Generated file name length.
|
static DateTime |
INVALID
Invalid time representation.
|
static DateTime |
MJD_EPOCH
MJD epoch (1858-11-17 00:00 UTC).
|
static DateTime |
UNIX_EPOCH
Unix epoch (1970-01-01 00:00 UTC).
|
static DateTime.Context |
UTC_CONTEXT
UTC context.
|
static DateTime |
WINDOWS_EPOCH
Windows epoch (1601-01-01 00:00 UTC).
|
Modifier and Type | Method and Description |
---|---|
DateTime |
after()
Returns a DateTime which would be just after this.
|
DateTime |
after(DateTime limit)
Returns the higher DateTime between this and after a limit.
|
DateTime |
after(ElapsedTime elapsed)
Returns a DateTime which would be some time after this.
|
DateTime |
after(long interval)
Returns a DateTime which would be at an interval after this.
|
static DateTime |
at(Timestamp timestamp)
Returns a DateTime from a Timestamp.
|
DateTime |
before()
Returns a DateTime which would be some time after this. /** Returns a
DateTime which would be just before this.
|
DateTime |
before(DateTime limit)
Returns the lower DateTime between this and before a limit.
|
DateTime |
before(ElapsedTime elapsed)
Returns a DateTime which would be some time before this.
|
DateTime |
before(long interval)
Returns a DateTime which would be at an interval before this.
|
static void |
clearSimulatedTime()
Clears the simulated time.
|
int |
compareTo(DateTime other) |
static DateTime.Context |
defaultContext()
Returns the default context.
|
boolean |
equals(Object other) |
DateTime |
floored(ElapsedTime whole)
Returns a floored DateTime.
|
DateTime |
floored(long whole)
Returns a floored DateTime based on this with respect to a given time
interval.
|
static DateTime |
fromBytes(byte[] bytes)
Returns a DateTime from a bytes representation.
|
static DateTime |
fromDataInput(DataInput source)
Reads in an external representation of a DateTime.
|
static DateTime |
fromFields(DateTime.Fields fields)
Returns a DateTime built from fields.
|
static DateTime |
fromInstant(Instant instant)
Returns a DateTime built from an Instant.
|
static DateTime |
fromMillis(long millis)
Returns a DateTime for the specified number of milliseconds since
1970-01-01 00:00:00.
|
static DateTime |
fromRaw(long raw)
Returns a DateTime from an internal (raw) representation.
|
static Optional<DateTime> |
fromString(Optional<String> timeString)
Returns a DateTime decoded from a time string.
|
static DateTime |
fromString(String timeString)
Returns a DateTime decoded from a time string.
|
static DateTime |
fromWin32(long win32)
Returns a DateTime from Win32::FileTime.
|
static DateTime |
fromZonedDateTime(ZonedDateTime zonedDateTime)
Returns a DateTime built from a ZonedDateTime.
|
int |
getDayOfWeek()
Gets the day of week.
|
static TimeZone |
getTimeZone()
Gets the time zone.
|
static ZoneId |
getZoneId()
Gets the ZoneId.
|
int |
hashCode() |
boolean |
isAfter(DateTime other)
Asks if this is after an other DateTime.
|
boolean |
isAfter(TimeInterval interval)
Asks if this is after a TimeInterval.
|
boolean |
isAtBeginning(TimeInterval interval)
Asks if this is at the beginning of a TimeInterval.
|
boolean |
isAtEnd(TimeInterval interval)
Asks if this is at the end of a TimeInterval.
|
boolean |
isBefore(DateTime other)
Asks if this is before an other DateTime.
|
boolean |
isBefore(TimeInterval interval)
Asks if this is before a TimeInterval.
|
boolean |
isBeginningOfTime()
Asks if this is the beginning of time.
|
boolean |
isEndOfTime()
Asks if this is the end of time.
|
boolean |
isInside(TimeInterval interval)
Asks if this is inside a TimeInterval.
|
boolean |
isInvalid()
Asks if this is the invalid DateTime.
|
boolean |
isNotAfter(DateTime other)
Asks if this is not after an other DateTime.
|
boolean |
isNotAfter(TimeInterval interval)
Asks if this is not after a TimeInterval.
|
boolean |
isNotBefore(DateTime other)
Asks if this is not before an other DateTime.
|
boolean |
isNotBefore(TimeInterval interval)
Asks if this is not before a TimeInterval.
|
static DateTime |
max(Collection<DateTime> dateTimes)
Returns the maximum DateTime instance.
|
static DateTime |
max(DateTime... dateTimes)
Returns the maximum DateTime instance.
|
DateTime |
midnight()
Returns a DateTime from this at midnight.
|
static DateTime |
min(Collection<DateTime> dateTimes)
Returns the minimum DateTime instance.
|
static DateTime |
min(DateTime... dateTimes)
Returns the minimum DateTime instance.
|
DateTime |
nextDay()
Returns a DateTime from this at midnight on the next day.
|
DateTime |
noon()
Returns a DateTime from this at noon.
|
DateTime |
notAfter(DateTime limit)
Returns the lower DateTime between this and a limit.
|
DateTime |
notBefore(DateTime limit)
Returns the higher DateTime between this and a limit.
|
static DateTime |
now()
Returns a DateTime for the current or simulated time.
|
DateTime |
previousDay()
Returns a DateTime from this at midnight on the previous day.
|
static Optional<DateTime> |
readExternal(ObjectInput source)
Reads in an external representation of a DateTime.
|
static void |
resetTimeZone()
Resets the time zone.
|
DateTime |
rounded(ElapsedTime whole)
Returns a rounded DateTime.
|
DateTime |
rounded(long whole)
Returns a rounded DateTime.
|
double |
scaled(ElapsedTime whole)
Returns a scaled representation of time.
|
double |
scaled(long whole)
Returns a scaled representation of time.
|
static void |
simulateTime(DateTime simulatedTime)
Simulates the supplied time as current.
|
static void |
simulateTimeZone(TimeZone timeZone)
Simulates the supplied time zone.
|
ElapsedTime |
sub(DateTime other)
Substracts an other DateTime from this.
|
String |
toBaseString()
Provides a base string representation of a this.
|
byte[] |
toBytes()
Returns a bytes representation of itself.
|
void |
toDataOutput(DataOutput destination)
Sends to a data output.
|
DateTime.Fields |
toFields()
Returns this as fields.
|
String |
toFileName()
Provides a String representation of this usable as a file name.
|
String |
toFullString()
Provides a full extended string representation of this.
|
String |
toHexString()
Provides an hexadecimal String representation of the internal value.
|
Instant |
toInstant()
Returns an Instant representation.
|
long |
toMillis()
Returns the number of milliseconds since 1970-01-01 00:00:00 UTC.
|
String |
toOrdinalString()
Provides an ordinal string representation of this.
|
long |
toRaw()
Returns the internal (raw) representation of time.
|
String |
toString() |
Timestamp |
toTimestamp()
Returns the time in a Timestamp.
|
String |
toURLString()
Provides a URL compatible representation of this.
|
long |
toWin32()
Returns the number of 100 nanoseconds since 1601-01-01 00:00:00 UTC.
|
ZonedDateTime |
toZonedDateTime()
Returns a ZonedDateTime representation of this.
|
DateTime |
valueOf(String timeString)
Returns a DateTime decoded from a time String.
|
static void |
writeExternal(Optional<DateTime> dateTime,
ObjectOutput destination)
Writes out an external representation of a DateTime.
|
public static final DateTime BEGINNING_OF_TIME
public static final String BEGINNING_OF_TIME_STRING
public static final DateTime END_OF_TIME
public static final String END_OF_TIME_STRING
public static final int FILE_NAME_LENGTH
public static final DateTime INVALID
public static final DateTime MJD_EPOCH
public static final DateTime UNIX_EPOCH
public static final DateTime.Context UTC_CONTEXT
public static final DateTime WINDOWS_EPOCH
@Nonnull @CheckReturnValue public static DateTime at(@Nonnull Timestamp timestamp)
timestamp
- The Timestamp.public static void clearSimulatedTime()
@Nonnull @CheckReturnValue public static DateTime.Context defaultContext()
@Nonnull @CheckReturnValue public static DateTime fromBytes(@Nonnull byte[] bytes)
bytes
- The bytes representation.IllegalArgumentException
- When the time value is out of range.@Nonnull @CheckReturnValue public static DateTime fromDataInput(@Nonnull DataInput source) throws IOException
source
- The source.IOException
- When an I/O error occurs.@Nonnull @CheckReturnValue public static DateTime fromFields(@Nonnull DateTime.Fields fields)
fields
- The fields.@Nonnull @CheckReturnValue public static DateTime fromInstant(@Nonnull Instant instant)
instant
- The Instant.@Nonnull @CheckReturnValue public static DateTime fromMillis(long millis)
millis
- The number of milliseconds since 1970-01-01 00:00:00.@Nonnull @CheckReturnValue public static DateTime fromRaw(long raw)
raw
- The internal (raw) representation.@Nonnull @CheckReturnValue public static Optional<DateTime> fromString(@Nonnull Optional<String> timeString)
It accepts as input the output of toString()
,
toFullString()
, toHexString()
or
Timestamp.toString()
. This input may also be null or empty.
timeString
- The optional time string.IllegalArgumentException
- When the time string is invalid.@Nonnull @CheckReturnValue public static DateTime fromString(@Nonnull String timeString)
It accepts as input the output of toString()
,
toFullString()
, toHexString()
or
Timestamp.toString()
. This input must not be null or empty.
timeString
- The time string.IllegalArgumentException
- When the time string is invalid.@Nonnull @CheckReturnValue public static DateTime fromWin32(long win32)
win32
- The Win32::FileTime.@Nonnull @CheckReturnValue public static DateTime fromZonedDateTime(@Nonnull ZonedDateTime zonedDateTime)
zonedDateTime
- The ZonedDateTime.@Nonnull @CheckReturnValue public static TimeZone getTimeZone()
@Nonnull @CheckReturnValue public static ZoneId getZoneId()
@Nonnull @CheckReturnValue public static DateTime max(@Nonnull Collection<DateTime> dateTimes)
dateTimes
- The DateTime instances.@Nonnull @CheckReturnValue public static DateTime max(@Nonnull DateTime... dateTimes)
dateTimes
- The DateTime instances.@Nonnull @CheckReturnValue public static DateTime min(@Nonnull Collection<DateTime> dateTimes)
dateTimes
- The DateTime instances.@Nonnull @CheckReturnValue public static DateTime min(@Nonnull DateTime... dateTimes)
dateTimes
- The DateTime instances.@Nonnull @CheckReturnValue public static DateTime now()
@Nonnull @CheckReturnValue public static Optional<DateTime> readExternal(@Nonnull ObjectInput source) throws IOException
This is a helper method for
Externalizable
objects containing a
DateTime.
source
- The source.IOException
- When an I/O error occurs.public static void resetTimeZone()
public static void simulateTime(@Nonnull DateTime simulatedTime)
This is used by tests scenarios.
simulatedTime
- The simulated time.public static void simulateTimeZone(@Nonnull TimeZone timeZone)
timeZone
- The simulated time zone.public static void writeExternal(@Nonnull Optional<DateTime> dateTime, @Nonnull ObjectOutput destination) throws IOException
This is a helper method for
Externalizable
objects containing a
DateTime.
dateTime
- The optional DateTime.destination
- The destination.IOException
- When an I/O error occurs.@Nonnull @CheckReturnValue public DateTime after()
Note: if this is either the beginning or the end of time, the time change is skipped.
@Nonnull @CheckReturnValue public DateTime after(@Nonnull DateTime limit)
limit
- The limit.@Nonnull @CheckReturnValue public DateTime after(@Nonnull ElapsedTime elapsed)
elapsed
- An elapsed time.@Nonnull @CheckReturnValue public DateTime after(long interval)
interval
- A number of 100 nanoseconds.IllegalArgumentException
- When the time value is out of range.@Nonnull @CheckReturnValue public DateTime before()
Note: if this is either the beginning or the end of time, the time change is skipped.
@Nonnull @CheckReturnValue public DateTime before(@Nonnull DateTime limit)
limit
- The limit.@Nonnull @CheckReturnValue public DateTime before(@Nonnull ElapsedTime elapsed)
elapsed
- An elapsed time.@Nonnull @CheckReturnValue public DateTime before(long interval)
interval
- A number of 100 nanoseconds.IllegalArgumentException
- When the interval or time value is out
of range.public int compareTo(DateTime other)
compareTo
in interface Comparable<DateTime>
public boolean equals(Object other)
equals
in class Object
@Nonnull @CheckReturnValue public DateTime floored(@Nonnull ElapsedTime whole)
whole
- An ElapsedTime representing a whole value.@Nonnull @CheckReturnValue public DateTime floored(long whole)
whole
- An internal representation (raw) of a whole value.@CheckReturnValue public int getDayOfWeek()
public int hashCode()
hashCode
in class Object
@CheckReturnValue public boolean isAfter(@Nonnull DateTime other)
other
- An other DateTime.@CheckReturnValue public boolean isAfter(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isAtBeginning(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isAtEnd(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isBefore(@Nonnull DateTime other)
other
- An other DateTime.@CheckReturnValue public boolean isBefore(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isBeginningOfTime()
@CheckReturnValue public boolean isEndOfTime()
@CheckReturnValue public boolean isInside(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isInvalid()
@CheckReturnValue public boolean isNotAfter(@Nonnull DateTime other)
other
- An other DateTime.@CheckReturnValue public boolean isNotAfter(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@CheckReturnValue public boolean isNotBefore(@Nonnull DateTime other)
other
- An other DateTime.@CheckReturnValue public boolean isNotBefore(@Nonnull TimeInterval interval)
interval
- The TimeInterval.@Nonnull @CheckReturnValue public DateTime midnight()
@Nonnull @CheckReturnValue public DateTime nextDay()
@Nonnull @CheckReturnValue public DateTime noon()
@Nonnull @CheckReturnValue public DateTime notAfter(@Nonnull DateTime limit)
limit
- The limit.@Nonnull @CheckReturnValue public DateTime notBefore(@Nonnull DateTime limit)
limit
- The limit.@Nonnull @CheckReturnValue public DateTime previousDay()
@Nonnull @CheckReturnValue public DateTime rounded(@Nonnull ElapsedTime whole)
whole
- An ElapsedTime representing a whole value.@Nonnull @CheckReturnValue public DateTime rounded(long whole)
whole
- An internal representation (raw) of a whole value.@Nonnull @CheckReturnValue public double scaled(@Nonnull ElapsedTime whole)
whole
- An ElapsedTime representing a whole value.@CheckReturnValue public double scaled(long whole)
whole
- An internal representation (raw) of a whole value.@Nonnull @CheckReturnValue public ElapsedTime sub(@Nonnull DateTime other)
other
- The other DateTime.@Nonnull @CheckReturnValue public String toBaseString()
Generates a base string in ISO 8601 format adjusted to astronomical conventions.
@Nonnull @CheckReturnValue public byte[] toBytes()
public void toDataOutput(@Nonnull DataOutput destination) throws IOException
destination
- The destination.IOException
- On I/O exception.@Nonnull @CheckReturnValue public DateTime.Fields toFields()
@Nonnull @CheckReturnValue public String toFileName()
To make sure that the lexical and chronological order of the representations are in sync, the time zone is set to GMT. The representation is then produced from a full String representation with the '-' and ':' characters removed.
@Nonnull @CheckReturnValue public String toFullString()
Generates an extended tring in ISO 8601 format adjusted to astronomical conventions.
@Nonnull @CheckReturnValue public String toHexString()
@Nonnull @CheckReturnValue public Instant toInstant()
@CheckReturnValue public long toMillis()
@Nonnull @CheckReturnValue public String toOrdinalString()
Generates a string in ISO 8601 format adjusted to astronomical conventions with the date in ordinal (yyyy-ddd) representation.
@CheckReturnValue public long toRaw()
public String toString()
toString
in class Object
@Nonnull @CheckReturnValue public Timestamp toTimestamp()
@Nonnull @CheckReturnValue public String toURLString()
@CheckReturnValue public long toWin32()
@Nonnull @CheckReturnValue public ZonedDateTime toZonedDateTime()
@Nonnull @CheckReturnValue public DateTime valueOf(@Nonnull String timeString) throws IllegalArgumentException
It accepts as input the output of toString()
,
toFullString()
, toHexString()
or
Timestamp.toString()
. The instance is used as a reference when
the year is missing.
timeString
- The time String.IllegalArgumentException
- When the time String is invalid.Copyright © 2003-2019 Serge Brisson. All Rights Reserved.