Package com.cedarsoftware.util

Class DateUtilities

java.lang.Object
com.cedarsoftware.util.DateUtilities
public final class DateUtilities extends Object
Utility for parsing String dates with optional times, supporting a wide variety of formats and patterns. Handles inconsistent input formats, optional time components, and various timezone specifications.

Supported Date Formats

FormatExampleDescription
Numeric with separators 12-31-2023, 12/31/2023, 12.31.2023 mm is 1-12 or 01-12, dd is 1-31 or 01-31, yyyy is 0000-9999
ISO-style 2023-12-31, 2023/12/31, 2023.12.31 yyyy-mm-dd format with flexible separators (-, /, .)
Month first January 6th, 2024 Month name (full or 3-4 letter), day with optional suffix, year
Day first 17th January 2024 Day with optional suffix, month name, year
Year first 2024 January 31st Year, month name, day with optional suffix
Unix style Sat Jan 6 11:06:10 EST 2024 Day of week, month, day, time, timezone, year

Supported Time Formats

FormatExampleDescription
Basic time 13:30 24-hour format (00-23:00-59)
With seconds 13:30:45 Includes seconds (00-59)
With fractional seconds 13:30:45.123456 Variable precision fractional seconds
With offset 13:30+01:00, 13:30:45-0500 Supports +HH:mm, +HHmm, +HH, -HH:mm, -HHmm, -HH, Z
With timezone 13:30 EST, 13:30:45 America/New_York Supports abbreviations and full zone IDs

Special Features

  • Supports Unix epoch milliseconds (e.g., "1640995200000")
  • Optional day-of-week in any position (ignored in date calculation)
  • Flexible date/time separator (space or 'T')
  • Time can appear before or after date
  • Extensive timezone support including abbreviations and full zone IDs
  • Handles ambiguous timezone abbreviations with population-based resolution
  • Thread-safe implementation

Usage Example


 // Basic parsing with system default timezone
 Date date1 = DateUtilities.parseDate("2024-01-15 14:30:00");

 // Parsing with specific timezone
 ZonedDateTime date2 = DateUtilities.parseDate("2024-01-15 14:30:00",
     ZoneId.of("America/New_York"), true);

 // Parsing Unix style date
 Date date3 = DateUtilities.parseDate("Tue Jan 15 14:30:00 EST 2024");
Author:
John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

  • Field Details

    • ABBREVIATION_TO_TIMEZONE

      public static final Map<String,String> ABBREVIATION_TO_TIMEZONE

  • Method Details

    • parseDate

      public static Date parseDate(String dateStr)
      Original API. If the date-time given does not include a timezone offset or name, then ZoneId.systemDefault() will be used. We recommend using parseDate(String, ZoneId, boolean) version, so you can control the default timezone used when one is not specified.
      Parameters:
      dateStr - String containing a date. If there is excess content, it will throw an IllegalArgumentException.
      Returns:
      Date instance that represents the passed in date. See comments at top of class for supported formats. This API is intended to be super flexible in terms of what it can parse. If a null or empty String is passed in, null will be returned.

    • parseDate

      public static ZonedDateTime parseDate(String dateStr, ZoneId defaultZoneId, boolean ensureDateTimeAlone)
      Main API. Retrieve date-time from passed in String. The boolean ensureDateTimeAlone, if set true, ensures that no other non-date content existed in the String.
      Parameters:
      dateStr - String containing a date. See DateUtilities class Javadoc for all the supported formats.
      defaultZoneId - ZoneId to use if no timezone offset or name is given. Cannot be null.
      ensureDateTimeAlone - If true, if there is excess non-Date content, it will throw an IllegalArgument exception.
      Returns:
      ZonedDateTime instance converted from the passed in date String. See comments at top of class for supported formats. This API is intended to be super flexible in terms of what it can parse. If a null or empty String is passed in, null will be returned.