@CalendarType(value="iso8601") public final class Moment extends TimePoint<java.util.concurrent.TimeUnit,Moment> implements UniversalTime, Temporal<UniversalTime>
Represents an instant/moment on the universal timeline with reference to the timezone UTC (UTC+00:00 / Greenwich-meridian).
The JDK-equivalent is traditionally the class java.util.Date.
In contrast to that old class this class stores the elapsed time not just
in millisecond but in nanosecond precision on 96-bit base.
Following elements which are declared as constants are registered by this class with access in UTC timezone:
Furthermore, most local elements like PlainTime.ISO_HOUR etc.
registered in class PlainTimestamp or those defined in
Weekmodel are indirectly supported via the queries in the
interface ZonalElement. A Moment is also capable of
delivering the date- and time-values in a different timezone if the
method toZonalTimestamp(TZID) is called. If zonal operators
are defined by any elements then manipulations of related data are
possible in any timezone.
Time arithmetic
The main time units are defined by SI (counting possible
UTC-leapseconds) and TimeUnit. Latter unit type can be used
if a better interoperability is needed for external APIs which ignore
leapseconds. Both kinds of time units can be used in the methods
plus(long, unit), minus(long, unit) and
until(Moment, unit).
| Modifier and Type | Field and Description |
|---|---|
static ChronoElement<java.lang.Integer> |
FRACTION
Represents the nano-fraction of current second.
|
static ChronoElement<java.lang.Long> |
POSIX_TIME
Represents the POSIX-time in seconds since UNIX-epoch.
|
static Moment |
UNIX_EPOCH
Start of UNIX-era = [1970-01-01T00:00:00,000000000Z].
|
| Modifier and Type | Method and Description |
|---|---|
static TimeAxis<java.util.concurrent.TimeUnit,Moment> |
axis()
Provides a static access to the associated time axis respective
chronology which contains the chronological rules.
|
int |
compareTo(Moment moment)
Compares two time points preferably by their temporal positions
on the common time axis.
|
boolean |
equals(java.lang.Object obj)
Compares the whole state of this instance with given object.
|
static TemporalFormatter<Moment> |
formatter(DisplayMode mode,
java.util.Locale locale,
TZID tzid)
Creates a new formatter which uses the given display mode and locale
for formatting and parsing moments in given timezone.
|
static <P extends ChronoPattern<P>> |
formatter(java.lang.String formatPattern,
P patternType,
java.util.Locale locale,
TZID tzid)
Creates a new formatter which uses the given pattern and locale
for formatting and parsing moments in given timezone.
|
static TemporalFormatter<Moment> |
formatterRFC1123()
Defines the RFC-1123-format which is for example used in mail
headers.
|
static Moment |
from(UnixTime ut)
Common conversion method.
|
long |
getElapsedTime(TimeScale scale)
Represents this timestamp as elpased seconds on given time scale.
|
int |
getNanosecond()
Yields the nanosecond fraction of current second.
|
int |
getNanosecond(TimeScale scale)
Represents the nanosecond part on the given time scale.
|
long |
getPosixTime()
Counts the seconds elapsed since UNIX epoch
[1970-01-01T00:00:00Z] in UTC timezone.
|
int |
hashCode()
Subclasses must redefine this method corresponding to the
behaviour of
equals(). |
ZonalDateTime |
inLocalView()
Creates a combination of this moment and system timezone.
|
ZonalDateTime |
inZonalView(java.lang.String tzid)
Creates a combination of this moment and given timezone.
|
ZonalDateTime |
inZonalView(TZID tzid)
Creates a combination of this moment and given timezone.
|
boolean |
isAfter(UniversalTime temporal)
Queries if this object is after given object on a timeline.
|
boolean |
isBefore(UniversalTime temporal)
Queries if this object is before given object on a timeline.
|
boolean |
isLeapSecond()
Queries if this time point is within a positive leapsecond.
|
boolean |
isSimultaneous(UniversalTime temporal)
Queries if this object and given object have the same position
on the time axis.
|
static TemporalFormatter<Moment> |
localFormatter(DisplayMode mode)
Creates a new formatter which uses the given display mode in the
default locale for formatting and parsing UTC-timestamps.
|
static <P extends ChronoPattern<P>> |
localFormatter(java.lang.String formatPattern,
P patternType)
Creates a new formatter which uses the given pattern in the
default locale for formatting and parsing UTC-timestamps.
|
Moment |
minus(long amount,
SI unit)
Subtracts an amount of given SI-unit from this timestamp
on the UTC time scale.
|
static ChronoOperator<Moment> |
nextLeapSecond()
Tries to determine the next coming leap second.
|
static Moment |
of(long elapsedTime,
int nanosecond,
TimeScale scale)
Creates a new UTC-timestamp by given time coordinates on given
time scale.
|
static Moment |
of(long elapsedTime,
TimeScale scale)
Equivalent to
Moment.of(elapsedTime, 0, scale). |
Moment |
plus(long amount,
SI unit)
Adds an amount of given SI-unit to this timestamp
on the UTC time scale.
|
PlainTimestamp |
toLocalTimestamp()
Converts this instance to a local timestamp in the system
timezone.
|
java.lang.String |
toString()
Provides a canonical representation in the ISO-format
[yyyy-MM-ddTHH:mm:ss,fffffffffZ].
|
java.lang.String |
toString(TimeScale scale)
Creates a formatted view of this instance taking in account
given time scale.
|
PlainTimestamp |
toZonalTimestamp(java.lang.String tzid)
Converts this instance to a local timestamp in given timezone.
|
PlainTimestamp |
toZonalTimestamp(TZID tzid)
Converts this instance to a local timestamp in given timezone.
|
java.math.BigDecimal |
transform(TimeScale scale)
Represents this timestamp as decimal value in given time scale.
|
long |
until(Moment end,
SI unit)
Calculates the time distance between this timestamp and given
end timestamp in given SI-unit on the UTC time scale.
|
max, min, minus, minus, plus, plus, until, untilcontains, get, get, getMaximum, getMinimum, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, withpublic static final Moment UNIX_EPOCH
Start of UNIX-era = [1970-01-01T00:00:00,000000000Z].
public static final ChronoElement<java.lang.Long> POSIX_TIME
Represents the POSIX-time in seconds since UNIX-epoch.
public static final ChronoElement<java.lang.Integer> FRACTION
Represents the nano-fraction of current second.
public static Moment of(long elapsedTime, TimeScale scale)
Equivalent to Moment.of(elapsedTime, 0, scale).
elapsedTime - elapsed seconds on given time scalescale - time scale referencejava.lang.IllegalArgumentException - if elapsed time is out of range limits
beyond year +/-999,999,999 or out of time scale rangejava.lang.IllegalStateException - if time scale is not POSIX but
leap second support is switched off by configurationLeapSeconds.isEnabled()public static Moment of(long elapsedTime, int nanosecond, TimeScale scale)
Creates a new UTC-timestamp by given time coordinates on given time scale.
The given elapsed time elapsedTime will be internally
transformed into the UTC-epochtime, should another time scale than UTC
be given. The time scale TAI will only be supported earliest on UTC
start 1972-01-01, the time scale GPS earliest on 1980-01-06.
elapsedTime - elapsed seconds on given time scalenanosecond - nanosecond fraction of last secondscale - time scale referencejava.lang.IllegalArgumentException - if the nanosecond is not in the range
0 <= nanosecond <= 999,999,999 or if elapsed time is
out of supported range limits beyond year +/-999,999,999 or
out of time scale rangejava.lang.IllegalStateException - if time scale is not POSIX but
leap second support is switched off by configurationLeapSeconds.isEnabled()public static Moment from(UnixTime ut)
Common conversion method.
ut - UNIX-timestampMomentpublic long getPosixTime()
UnixTimeCounts the seconds elapsed since UNIX epoch [1970-01-01T00:00:00Z] in UTC timezone.
getPosixTime in interface UnixTimepublic long getElapsedTime(TimeScale scale)
UniversalTimeRepresents this timestamp as elpased seconds on given time scale.
The method getPosixTime() inherited from UnixTime
is equivalent to getElapsedTime(TimeScale.POSIX) and relates
to the UNIX-epoch 1970-01-01. The time scale UTC starts two years
later however and also counts leapseconds.
getElapsedTime in interface UniversalTimescale - time scale referencepublic int getNanosecond()
UnixTimeYields the nanosecond fraction of current second.
As time unit, the nanosecond is defined as one billionth part of a second).
getNanosecond in interface UnixTime0 - 999.999.999public int getNanosecond(TimeScale scale)
UniversalTimeRepresents the nanosecond part on the given time scale.
The method with the same name and without argument inherited from
super interface UnixTime is identical to this method if the
time scale is either POSIX or UTC.
getNanosecond in interface UniversalTimescale - time scale referencepublic boolean isLeapSecond()
UniversalTimeQueries if this time point is within a positive leapsecond.
If the support for UTC-leapseconds is switched off per configuration
then this method will always yield false.
isLeapSecond in interface UniversalTimetrue if this instance represents a positive
leap second else falseLeapSeconds.isEnabled()public static ChronoOperator<Moment> nextLeapSecond()
Tries to determine the next coming leap second.
null
if unknown or disabledpublic java.math.BigDecimal transform(TimeScale scale)
Represents this timestamp as decimal value in given time scale.
scale - time scale referencejava.lang.IllegalArgumentException - if this instance is out of range
for given time scalepublic boolean isAfter(UniversalTime temporal)
TemporalQueries if this object is after given object on a timeline.
isAfter in interface Temporal<UniversalTime>temporal - object this instance is compared totrue if this instance is temporally after
temporal else falsepublic boolean isBefore(UniversalTime temporal)
TemporalQueries if this object is before given object on a timeline.
isBefore in interface Temporal<UniversalTime>temporal - object this instance is compared totrue if this instance is temporally before
temporal else falsepublic boolean isSimultaneous(UniversalTime temporal)
TemporalQueries if this object and given object have the same position on the time axis.
Is equivalent to !isAfter(temporal) && !isBefore(temporal).
This method differs from the Object-method equals()
such that first the comparison type must be a temporal one and second
that only temporal-only state will be considered.
isSimultaneous in interface Temporal<UniversalTime>temporal - object this instance is compared totrue if this instance is temporally equal
to temporal else falsepublic PlainTimestamp toLocalTimestamp()
Converts this instance to a local timestamp in the system timezone.
Timezone.ofSystem(),
toZonalTimestamp(TZID),
toZonalTimestamp(String)public PlainTimestamp toZonalTimestamp(TZID tzid)
Converts this instance to a local timestamp in given timezone.
tzid - timezone idjava.lang.IllegalArgumentException - if given timezone cannot be loadedtoLocalTimestamp()public PlainTimestamp toZonalTimestamp(java.lang.String tzid)
Converts this instance to a local timestamp in given timezone.
tzid - timezone idjava.lang.IllegalArgumentException - if given timezone cannot be loadedtoZonalTimestamp(TZID),
toLocalTimestamp()public ZonalDateTime inLocalView()
Creates a combination of this moment and system timezone.
A direct conversion to a local timestamp can be achieved by
toLocalTimestamp().
java.lang.IllegalArgumentException - if this moment is a leapsecond and
shall be combined with a non-full-minute-timezone-offsetpublic ZonalDateTime inZonalView(TZID tzid)
Creates a combination of this moment and given timezone.
A direct conversion to a zonal timestamp can be achieved by
toZonalTimestamp(TZID).
tzid - timezone idjava.lang.IllegalArgumentException - if this moment is a leapsecond and
shall be combined with a non-full-minute-timezone-offset or
if given timezone cannot be loadedpublic ZonalDateTime inZonalView(java.lang.String tzid)
Creates a combination of this moment and given timezone.
A direct conversion to a zonal timestamp can be achieved by
toZonalTimestamp(String).
tzid - timezone idjava.lang.IllegalArgumentException - if this moment is a leapsecond and
shall be combined with a non-full-minute-timezone-offset or
if given timezone cannot be loadedpublic Moment plus(long amount, SI unit)
Adds an amount of given SI-unit to this timestamp on the UTC time scale.
amount - amount in units to be addedunit - time unit defined in UTC time spacejava.lang.UnsupportedOperationException - if either this moment
or the result are before 1972java.lang.ArithmeticException - in case of overflowjava.lang.IllegalArgumentException - if new moment is out of range limitspublic Moment minus(long amount, SI unit)
Subtracts an amount of given SI-unit from this timestamp on the UTC time scale.
amount - amount in SI-units to be subtractedunit - time unit defined in UTC time spacejava.lang.UnsupportedOperationException - if either this moment
or the result are before 1972java.lang.ArithmeticException - in case of overflowpublic long until(Moment end, SI unit)
Calculates the time distance between this timestamp and given end timestamp in given SI-unit on the UTC time scale.
end - end time pointunit - time unit defined in UTC time spacejava.lang.UnsupportedOperationException - if any moment is before 1972public static <P extends ChronoPattern<P>> TemporalFormatter<Moment> localFormatter(java.lang.String formatPattern, P patternType)
Creates a new formatter which uses the given pattern in the default locale for formatting and parsing UTC-timestamps.
Note: The formatter can be adjusted to other locales and timezones however.
P - generic pattern typeformatPattern - format definition as patternpatternType - pattern dialectMoment-objects
using system locale and system timezonejava.lang.IllegalArgumentException - if resolving of pattern failspublic static TemporalFormatter<Moment> localFormatter(DisplayMode mode)
Creates a new formatter which uses the given display mode in the default locale for formatting and parsing UTC-timestamps.
Note: The formatter can be adjusted to other locales and timezones however.
mode - formatting styleMoment-objects
using system locale and system timezonejava.lang.IllegalStateException - if format pattern cannot be retrievedpublic static <P extends ChronoPattern<P>> TemporalFormatter<Moment> formatter(java.lang.String formatPattern, P patternType, java.util.Locale locale, TZID tzid)
Creates a new formatter which uses the given pattern and locale for formatting and parsing moments in given timezone.
Note: The given timezone will be used in printing while it serves as replacement value during parsing (if the text is missing a timezone information). The formatter can be adjusted to other locales and timezones however.
P - generic pattern typeformatPattern - format definition as patternpatternType - pattern dialectlocale - locale settingtzid - timezone idMoment-objects
using given locale and timezonejava.lang.IllegalArgumentException - if resolving of pattern failslocalFormatter(String,ChronoPattern)public static TemporalFormatter<Moment> formatter(DisplayMode mode, java.util.Locale locale, TZID tzid)
Creates a new formatter which uses the given display mode and locale for formatting and parsing moments in given timezone.
Note: The given timezone will be used in printing while it serves as replacement value during parsing (if the text is missing a timezone information). The formatter can be adjusted to other locales and timezones however.
mode - formatting stylelocale - locale settingtzid - timezone idMoment-objects using given localejava.lang.IllegalStateException - if format pattern cannot be retrievedlocalFormatter(DisplayMode)public static TemporalFormatter<Moment> formatterRFC1123()
Defines the RFC-1123-format which is for example used in mail headers.
Equivalent to the pattern "[EEE, ]d MMM yyyy HH:mm[:ss] XX" where the timezone offset XX is modified such that in case of zero offset the expression "GMT" is preferred. As zero offset will also be accepted "UT" or "Z". The text elements will always be interpreted in English and are case-insensitive.
Note: In contrast to the RFC-1123-standard this method does not support military timezone abbreviations (A-Y) or north-american timezone names (EST, EDT, CST, CDT, MST, MDT, PST, PDT).
public int compareTo(Moment moment)
TimePointCompares two time points preferably by their temporal positions on the common time axis.
Implementation note: In order to make the natural order consistent
with equals() the whole state must be taken into account,
with preference for those attributes which define the temporal
position on the time axis.
compareTo in interface java.lang.Comparable<Moment>compareTo in class TimePoint<java.util.concurrent.TimeUnit,Moment>TimePoint.equals(Object)public boolean equals(java.lang.Object obj)
TimePointCompares the whole state of this instance with given object.
Implementations will usually define their state only based on the temporal position on the time axis because this is the most intuitive approach. Exceptions from this rule should be explicitly documented and reasoned.
equals in class TimePoint<java.util.concurrent.TimeUnit,Moment>TimePoint.compareTo(TimePoint)public int hashCode()
TimePointSubclasses must redefine this method corresponding to the
behaviour of equals().
public java.lang.String toString()
Provides a canonical representation in the ISO-format [yyyy-MM-ddTHH:mm:ss,fffffffffZ].
The fraction will only be printed if not zero. Example:
The expression Moment.of(1341100824, 210, TimeScale.UTC)
has the representation "2012-06-30T23:59:60,000000210Z".
public java.lang.String toString(TimeScale scale)
Creates a formatted view of this instance taking in account given time scale.
Moment moment =
PlainDate.of(2012, Month.JUNE, 30)
.at(PlainTime.of(23, 59, 59, 999999999))
.atUTC()
.plus(1, SI.SECONDS); // move to leap second
System.out.println(moment.toString(TimeScale.POSIX));
// Output: POSIX-2012-06-30T23:59:59,999999999Z
System.out.println(moment.toString(TimeScale.UTC));
// Output: UTC-2012-06-30T23:59:60,999999999Z
System.out.println(moment.toString(TimeScale.TAI));
// Output: TAI-2012-07-01T00:00:34,999999999Z
System.out.println(moment.toString(TimeScale.GPS));
// Output: GPS-2012-07-01T00:00:15,999999999Z
scale - time scale to be used for formattingjava.lang.IllegalArgumentException - if this instance is out of range
for given time scalegetElapsedTime(TimeScale)