Package net.time4j

Class ZonalDateTime

java.lang.Object
net.time4j.ZonalDateTime
All Implemented Interfaces:
TemporalAccessor, UnixTime, ChronoDisplay, ThreetenAdapter, UniversalTime
public final class ZonalDateTime extends Object implements ChronoDisplay, UniversalTime, ThreetenAdapter

Combination of UTC-moment and timezone.

An instance can be created by Moment.inLocalView() or Moment.inZonalView(...). This type mainly serves for various type conversions and incorporates a valid local timestamp as well as an universal time in UTC. If users wish to apply any kind of data manipulation then an object of this type has first to be converted to a local timestamp or to a global UTC-moment. Example: 

  Moment moment = ...;
  ZonalDateTime zdt = moment.inLocalView();

  // manipulation on local timeline
  PlainTimestamp localTSP = zdt.toTimestamp().plus(30, ClockUnit.SECONDS);

  // manipulation on global timeline
  Moment globalTSP = zdt.toMoment().plus(30, SI.SECONDS);

This class supports all elements which are supported by Moment and PlainTimestamp, too.

Since:
2.0
Author:
Meno Hochschild
See Also:
Moment.inLocalView(), Moment.inZonalView(TZID), Moment.inZonalView(String)

  • Method Details

    • compareByMoment

      public int compareByMoment​(ZonalDateTime zdt)

      Compares this instance with another instance on the global timeline (UTC).

      If the UTC-times are equal then and only then the local timestamps will be taken into account. Example: 

        List<String> dates =
      Arrays.asList("Tue, 29 Feb 2016 17:45:00 CET", "Tue, 29 Feb 2016 16:00:00 EST");
  TemporalFormatter<Moment> formatter =
      ChronoFormatter.ofMomentPattern(
          "EEE, dd MMM yyyy HH:mm:ss z", PatternType.CLDR, Locale.ENGLISH, ZonalOffset.UTC);
  ZonalDateTime maxDate =
      dates.stream()
      .map(s -> ZonalDateTime.parse(s, formatter))
      .max(ZonalDateTime::compareByMoment)
      .get();
  System.out.println(maxDate); // 2016-02-29T16UTC-05:00[America/New_York]
      Parameters:
      zdt - other instance to be compared with
      Returns:
      negative, zero or positive integer if this instance is earlier, simultaneous or later than given arg
      Since:
      3.16/4.13
      See Also:
      compareByLocalTimestamp(ZonalDateTime)

    • compareByLocalTimestamp

      public int compareByLocalTimestamp​(ZonalDateTime zdt)

      Compares this instance with another instance on the local timeline.

      If the local timestamps are equal then and only then the UTC-times will be taken into account.

      Parameters:
      zdt - other instance to be compared with
      Returns:
      negative, zero or positive integer if this instance is earlier, simultaneous or later than given arg
      Since:
      3.16/4.13
      See Also:
      compareByMoment(ZonalDateTime)

    • contains

      public boolean contains​(ChronoElement<?> element)
      Description copied from interface: ChronoDisplay

      Queries if the value for given chronological element can be accessed via get(element).

      If the argument is missing then this method will yield false. Note: Elements which are not registered but define a suitable rule are also accessible.

      Specified by:
      contains in interface ChronoDisplay
      Parameters:
      element - chronological element to be asked (optional)
      Returns:
      true if the element is registered or there is an element rule for evaluating the value else false
      See Also:
      ChronoDisplay.get(ChronoElement)

    • get

      public <V> V get​(ChronoElement<V> element)
      Description copied from interface: ChronoDisplay

      Returns the partial value associated with given chronological element.

      Specified by:
      get in interface ChronoDisplay
      Type Parameters:
      V - generic type of element value
      Parameters:
      element - element which has the value
      Returns:
      associated element value as object (never null)
      See Also:
      ChronoDisplay.contains(ChronoElement)

    • getInt

      public int getInt​(ChronoElement<Integer> element)
      Description copied from interface: ChronoDisplay

      Returns the partial value associated with given chronological element.

      Specified by:
      getInt in interface ChronoDisplay
      Parameters:
      element - element which has the value
      Returns:
      associated element value as int primitive or Integer.MIN_VALUE if not available
      See Also:
      ChronoDisplay.get(ChronoElement)

    • getMinimum

      public <V> V getMinimum​(ChronoElement<V> element)
      Description copied from interface: ChronoDisplay

      Yields the minimum value of given chronological element in the current context of this object.

      The definition of a minimum and a maximum does generally not imply that every intermediate value between minimum and maximum is valid in this context. For example in the timezone Europe/Berlin the hour [T02:00] will be invalid if switching to summer time.

      In most cases the minimum value is not dependent on this context.

      Specified by:
      getMinimum in interface ChronoDisplay
      Type Parameters:
      V - generic type of element value
      Parameters:
      element - element whose minimum value is to be evaluated
      Returns:
      minimum maybe context-dependent element value
      See Also:
      ChronoElement.getDefaultMinimum(), ChronoDisplay.getMaximum(ChronoElement)

    • getMaximum

      public <V> V getMaximum​(ChronoElement<V> element)
      Description copied from interface: ChronoDisplay

      Yields the maximum value of given chronological element in the current context of this object.

      Maximum values are different from minimum case often dependent on the context. An example is the element SECOND_OF_MINUTE whose maximum is normally 59 but can differ in UTC-context with leap seconds. Another more common example is the maximum of the element DAY_OF_MONTH (28-31) which is dependent on the month and year of this context (leap years!).

      Note: In timezone-related timestamps possible offset jumps inducing gaps on the local timeline will be conserved. That means that minimum and maximum do not guarantee a continuum of valid intermediate values.

      Specified by:
      getMaximum in interface ChronoDisplay
      Type Parameters:
      V - generic type of element value
      Parameters:
      element - element whose maximum value is to be evaluated
      Returns:
      maximum maybe context-dependent element value
      See Also:
      ChronoElement.getDefaultMaximum(), ChronoDisplay.getMinimum(ChronoElement)

    • hasTimezone

      public boolean hasTimezone()

      This object always has a timezone.

      Specified by:
      hasTimezone in interface ChronoDisplay
      Returns:
      true

    • getTimezone

      public TZID getTimezone()
      Description copied from interface: ChronoDisplay

      Returns the associated timezone ID for display purposes if available.

      Note: Although global types like Moment indeed have a timezone reference (namely UTC+00:00), such types will not support formatted output without explicitly giving a timezone for display purposes. Therefore calling this method on global types will throw an exception. This method is not just about any timezone reference but a timezone designed for display purposes.

      Specified by:
      getTimezone in interface ChronoDisplay
      Returns:
      timezone identifier if available
      See Also:
      ChronoDisplay.hasTimezone()

    • getOffset

      public ZonalOffset getOffset()

      Yields the timezone offset.

      Returns:
      offset relative to UTC+00:00
      Since:
      2.0

    • toMoment

      public Moment toMoment()

      Converts this object to a global UTC-moment.

      Returns:
      Moment

    • toTimestamp

      public PlainTimestamp toTimestamp()

      Converts this object to a zonal timestamp.

      Returns:
      PlainTimestamp

    • from

      public static ZonalDateTime from​(ZonedDateTime zdt)

      Short cut for TemporalType.ZONED_DATE_TIME.translate(zdt).

      Parameters:
      zdt - Threeten-equivalent of a zonal date-time
      Returns:
      ZonalDateTime
      Since:
      4.0
      See Also:
      TemporalType.ZONED_DATE_TIME

    • getElapsedTime

      public long getElapsedTime​(TimeScale scale)
      Description copied from interface: UniversalTime

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

      Specified by:
      getElapsedTime in interface UniversalTime
      Parameters:
      scale - time scale reference
      Returns:
      elapsed seconds in given time scale

    • getNanosecond

      public int getNanosecond​(TimeScale scale)
      Description copied from interface: UniversalTime

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

      Specified by:
      getNanosecond in interface UniversalTime
      Parameters:
      scale - time scale reference
      Returns:
      nanosecond fraction in given time scale

    • isLeapSecond

      public boolean isLeapSecond()
      Description copied from interface: UniversalTime

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

      Specified by:
      isLeapSecond in interface UniversalTime
      Returns:
      true if this instance represents a positive leap second else false
      See Also:
      LeapSeconds.isEnabled()

    • getPosixTime

      public long getPosixTime()
      Description copied from interface: UnixTime

      Counts the seconds elapsed since UNIX epoch [1970-01-01T00:00:00Z] in UTC timezone.

      Specified by:
      getPosixTime in interface UnixTime
      Returns:
      count of seconds since UNIX-epoch at [1970-01-01T00:00:00Z] without leap seconds in the timezone UTC (Greenwich)

    • getNanosecond

      public int getNanosecond()
      Description copied from interface: UnixTime

      Yields the nanosecond fraction of current second.

      As time unit, the nanosecond is defined as one billionth part of a second).

      Specified by:
      getNanosecond in interface UnixTime
      Returns:
      count of nanoseconds as fraction of last second in the range 0 - 999.999.999

    • print

      public String print​(TemporalFormatter<Moment> printer)

      Creates a formatted output of this instance.

      Parameters:
      printer - helps to format this instance
      Returns:
      formatted string
      Since:
      3.0

    • parse

      public static ZonalDateTime parse​(String text, TemporalFormatter<Moment> parser)

      Parses given text to a ZonalDateTime.

      Note: This method can be used in lambda expressions because it avoids checked exceptions.

      Parameters:
      text - text to be parsed
      parser - helps to parse given text
      Returns:
      parsed result
      Throws:
      IndexOutOfBoundsException - if the text is empty
      ChronoException - if parsing does not work (for example missing timezone information)
      Since:
      5.0

    • equals

      public boolean equals​(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()

      Yields a canonical representation in ISO-like-style.

      Overrides:
      toString in class Object
      Returns:
      String suitable only for debugging purposes
      See Also:
      print(TemporalFormatter)

    • toTemporalAccessor

      public ZonedDateTime toTemporalAccessor()
      Description copied from interface: ThreetenAdapter

      Converts this object to a TemporalAccessor.

      Any implementation is required to return a new object with a different concrete type, not this instance.

      Specified by:
      toTemporalAccessor in interface ThreetenAdapter
      Returns:
      converted Threeten-object (always as new object)

    • write

      public void write​(ObjectOutput output) throws IOException

      Writes this instance to given output (serialization).

      Warning: Serializing this instance is a heavy-weight-operation because the whole relevant timezone data will be written to given stream, not only the timezone-id.

      Parameters:
      output - object output
      Throws:
      IOException - if writing fails
      Since:
      3.1

    • read

      public static ZonalDateTime read​(ObjectInput input) throws IOException, ClassNotFoundException

      This is the reverse operation of write(ObjectOutput).

      Parameters:
      input - object input
      Returns:
      reconstructed instance of serialized ZonalDateTime
      Throws:
      IOException - if reading fails
      ClassNotFoundException - if class-loading fails
      IllegalArgumentException - in case of inconsistent data
      Since:
      3.1