Package org.kiwiproject.time

Class KiwiDateTimeConverters

java.lang.Object
org.kiwiproject.time.KiwiDateTimeConverters
public final class KiwiDateTimeConverters extends Object
A collection of small utility methods to convert between legacy Date and the Java 8 date/time API classes.

Mainly, these utilities save you some typing and having to remember the chains of method calls you need to make when doing these conversions.

All methods throw IllegalArgumentException if null values are passed into them.

Implementation Note:
Date, according to its JavaDoc, is "intended to reflect coordinated universal time (UTC)" though "it may not do so exactly". The utilities in this class convert arguments to UTC before converting to Date in order to reflect that intention.

  • Method Details

    • toDate

      public static Date toDate(LocalDate localDate)
      Convert the given LocalDate into its equivalent Date (epoch milliseconds using UTC). The time will be set to the start of the day.
      Parameters:
      localDate - the LocalDate to convert
      Returns:
      the converted Date

    • toDate

      public static Date toDate(LocalDateTime localDateTime)
      Convert the given LocalDateTime into its equivalent Date (epoch milliseconds using UTC).
      Parameters:
      localDateTime - the LocalDateTime to convert
      Returns:
      the converted Date

    • toDate

      public static Date toDate(ZonedDateTime zonedDateTime)
      Convert the given ZonedDateTime into its equivalent Date (epoch milliseconds using UTC).
      Parameters:
      zonedDateTime - the ZonedDateTime to convert
      Returns:
      the converted Date

    • toInstantOrNull

      public static @Nullable Instant toInstantOrNull(@Nullable Date date)
      Return the Instant converted from date, or null if date is null.

      This is a null-safe wrapper around Date.toInstant(), and is useful in situations when you might have a null date.

      Parameters:
      date - the Date to convert, may be null
      Returns:
      the converted Instant or null
      Implementation Note:
      This method only exists because Date.toInstant() is an instance method and obviously a NullPointerException is thrown if you attempt to call it when the receiver is null, i.e. maybeNullDate.toInstant().

    • toInstantOrNull

      public static @Nullable Instant toInstantOrNull(@Nullable Calendar calendar)
      Return the Instant converted from calendar, or null if calendar is null.

      This is a null-safe wrapper around Calendar.toInstant(), and is useful in situations when you might have a null calendar.

      Parameters:
      calendar - the Calendar to convert, may be null
      Returns:
      the converted Instant or null
      Implementation Note:
      This method only exists because Calendar.toInstant() is an instance method and obviously a NullPointerException is thrown if you attempt to call it when the receiver is null, i.e. maybeNullCalendar.toInstant().

    • toLocalDateUTC

      public static LocalDate toLocalDateUTC(Date date)
      Convert the given Date into its equivalent LocalDate in the UTC time zone.
      Parameters:
      date - the Date to convert
      Returns:
      the converted LocalDate

    • toLocalDate

      public static LocalDate toLocalDate(Date date, ZoneId zoneId)
      Convert the given Date into its equivalent LocalDate in the specified time zone.
      Parameters:
      date - the Date to convert
      zoneId - the time zone as a ZoneId
      Returns:
      the converted LocalDate

    • toLocalDateTimeUTC

      public static LocalDateTime toLocalDateTimeUTC(Date date)
      Convert the given Date into its equivalent LocalDateTime in the UTC time zone.
      Parameters:
      date - the Date to convert
      Returns:
      the converted LocalDateTime
      See Also:

    • toLocalDateTime

      public static LocalDateTime toLocalDateTime(Date date, ZoneId zoneId)
      Convert the given Date into its equivalent LocalDateTime in the specified time zone.
      Parameters:
      date - the Date to convert
      zoneId - the time zone as a ZoneId
      Returns:
      the converted LocalDateTime

    • toZonedDateTimeUTC

      public static ZonedDateTime toZonedDateTimeUTC(Date date)
      Convert the given Date into its equivalent ZonedDateTime in the UTC time zone.
      Parameters:
      date - the Date to convert
      Returns:
      the converted ZonedDateTime
      See Also:

    • toZonedDateTime

      public static ZonedDateTime toZonedDateTime(Date date, ZoneId zoneId)
      Convert the given Date into its equivalent ZonedDateTime in the specified time zone.
      Parameters:
      date - the Date to convert
      zoneId - the time zone as a ZoneId
      Returns:
      the converted ZonedDateTime

    • toZonedDateTimeOrNull

      public static @Nullable ZonedDateTime toZonedDateTimeOrNull(@Nullable GregorianCalendar calendar)
      Return the ZonedDateTime converted from calendar, or null if calendar is null.

      This is a null-safe wrapper around GregorianCalendar.toZonedDateTime(), and is useful in situations when you might have a null calendar.

      Parameters:
      calendar - the GregorianCalendar to convert, may be null
      Returns:
      the converted ZonedDateTime or null
      Implementation Note:
      This method only exists because GregorianCalendar.toZonedDateTime() is an instance method and obviously a NullPointerException is thrown if you attempt to call it when the receiver is null, i.e. maybeNullGregorianCalendar.toZonedDateTime(). Note also that toZonedDateTime is only in GregorianCalendar, not the base Calendar, which is the reason this accepts a GregorianCalendar argument.