Package com.aquima.interactions.foundation.text

Class DateFormat

java.lang.Object
com.aquima.interactions.foundation.text.DateFormat
All Implemented Interfaces:
Serializable
public final class DateFormat extends Object implements Serializable

This class is intended as a replacement for the java.text.SimpleDateFormat class. The SimpleDateFormat class is rather resource hungry and caused significant performance issues. This class addresses that issue by leaving out certain functionality supported by SimpleDateFormat, but which wasn't widely used.

Differences:

There are some notable differences between DateFormat and SimpleDateFormat that should be duly noted:

  • Contrary to SimpleDateFormat, DateFormat is not lenient by default.
  • DateFormat has a rather complex looking constructor since it has a less sophisticated parser and formatter...
  • ... Which is compensated by providing some static instances with commonly used date/time patterns.
  • When used in stead of new SimpleDateFormat instances, performance of DateFormat is equal to or better than SimpleDateFormat.
  • When used in stead of properly synchronized static SimpleDateFormat instances, performance of the format method of DateFormat is slightly less than SimpleDateFormat's format method.
  • DateFormat is properly synchronized. Calls from different threads will not override the internal buffer.
  • When using a pattern without separator symbols (e.g.: yyyyMMdd), the width of the pattern is considered fixed and any date string shorter or longer than the expected number of characters (8 in this case) will cause a ParseException to be thrown.
  • DateFormat will always format date values with the proper amount of leading zeroes, but will accept date strings with fields lacking those leading zeroes as long as the pattern used contains the proper separators.

Static instances and their equivalent SimpleDateFormat patterns:

The following table shows the static instances of DateFormat and their equivalent patterns when using a SimpleDateFormat instance:

The following table shows the static instances of DateFormat and their equivalent patterns when using a SimpleDateFormat instance
Static instance equivalent pattern
DateFormat.ISO_DATETIME yyyy-MM-dd HH:mm:ss
DateFormat.ISO_DATE yyyy-MM-dd
DateFormat.ISO_TIME HH:mm:ss
DateFormat.US_DATETIME yyyy/MM/dd HH:mm:ss
DateFormat.US_DATE yyyy/MM/dd
DateFormat.US_TIME HH:mm:ss
DateFormat.DD_MM_YYYY dd-MM-yyyy
DateFormat.DD_MM_YYYY_HH_MM_SS dd-MM-yyyy HH:mm:ss
DateFormat.DD_MM_YYYY_HH_MM dd-MM-yyyy HH:mm
DateFormat.YYYYMMDD yyyyMMdd

Examples:

Instead of:

final SimpleDateFormat sdf=new SimpleDateFormat("dd-MM-yyyy");
use:
final DateFormat ldf=DateFormat.DD_MM_YYYY;

Instead of:

final SimpleDateFormat sdf=new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
use:
final DateFormat ldf= DateFormat.ISO_DATETIME;

Note on ISO formats

The ISO format for date and time is widely used because of its resistancy to misinterpretation. Some more information about ISO 8601 may be found on the web (http://www.cl.cam.ac.uk/~mgk25/iso-time.html). Although the ISO formats do not require separator symbols, the ISO formats statically defined in this class do, in order to increase readability and further decrease the chance of misinterpretations.

Note on leap seconds

Like the SimpleDateFormat class, the DateFormat class does not support leap seconds.

Constructing a specialized format

It may be required to define a different date/time format in some occasions. This class provides a constructor to do so, although the necessary code may look rather cumbersome. For example, to define a format for a US-ish date followed by the time (using a period separator), one would use the format "yyyy/MM/dd HH.mm.ss". Using DateFormat's constructor this would become:

static final DateFormat ldf=new DateFormat(new Symbol[]{DateFormat.YEAR, DateFormat.SLASH, DateFormat.MONTH, DateFormat.SLASH, DateFormat.DATE, DateFormat.SPACE, DateFormat.HOUR, DateFormat.PERIOD, DateFormat.MINUTE, DateFormat.PERIOD, DateFormat.SECOND});
Don't forget to breathe... :)

Future plans

Currently there is no way to include text in the date/time string. This might be a nice addition to a later version. Although it will likely require the construction of a new instance of this class.

Since:
5.1
Author:
C. de Meijer, Jon van Leuven
See Also:

  • Field Details

    • ALLSYMBOLS

      protected static final List<IDateSymbol> ALLSYMBOLS

    • YEAR

      public static final IDateSymbol YEAR
      Convenience public field for constructing a non-default instance of this class.

    • MONTH

      public static final IDateSymbol MONTH
      Convenience public field for constructing a non-default instance of this class.

    • DATE

      public static final IDateSymbol DATE
      Convenience public field for constructing a non-default instance of this class.

    • HOUR

      public static final IDateSymbol HOUR
      Convenience public field for constructing a non-default instance of this class.

    • MINUTE

      public static final IDateSymbol MINUTE
      Convenience public field for constructing a non-default instance of this class.

    • SECOND

      public static final IDateSymbol SECOND
      Convenience public field for constructing a non-default instance of this class.

    • MILLISECOND

      public static final IDateSymbol MILLISECOND
      Convenience public field for constructing a non-default instance of this class.

    • CENTISECOND

      public static final IDateSymbol CENTISECOND
      Convenience public field for constructing a non-default instance of this class.

    • DECISECOND

      public static final IDateSymbol DECISECOND
      Convenience public field for constructing a non-default instance of this class.

    • PERIOD

      public static final SeparatorSymbol PERIOD
      Convenience public field for constructing a non-default instance of this class.

    • SEMICOLON

      public static final SeparatorSymbol SEMICOLON
      Convenience public field for constructing a non-default instance of this class.

    • COLON

      public static final SeparatorSymbol COLON
      Convenience public field for constructing a non-default instance of this class.

    • COMMA

      public static final SeparatorSymbol COMMA
      Convenience public field for constructing a non-default instance of this class.

    • DASH

      public static final SeparatorSymbol DASH
      Convenience public field for constructing a non-default instance of this class.

    • SLASH

      public static final SeparatorSymbol SLASH
      Convenience public field for constructing a non-default instance of this class.

    • SPACE

      public static final SeparatorSymbol SPACE
      Convenience public field for constructing a non-default instance of this class.

    • TIMEDESIGNATOR

      public static final SeparatorSymbol TIMEDESIGNATOR
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_SHORTYEAR

      public static final IDateSymbol FORMATONLY_SHORTYEAR
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_SHORTDATE

      public static final IDateSymbol FORMATONLY_SHORTDATE
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_SHORTMONTH

      public static final IDateSymbol FORMATONLY_SHORTMONTH
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_MERIDIEMMARKER

      public static final IDateSymbol FORMATONLY_MERIDIEMMARKER
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_SHORTHOURLEADINGZERO

      public static final IDateSymbol FORMATONLY_SHORTHOURLEADINGZERO
      Convenience public field for constructing a non-default instance of this class.

    • FORMATONLY_SHORTHOUR

      public static final IDateSymbol FORMATONLY_SHORTHOUR
      Convenience public field for constructing a non-default instance of this class.

    • SYMBOLS

      public static final IDateSymbol[] SYMBOLS
      Convenience public field for containing all the symbols.

    • ISO_DATE

      public static final DateFormat ISO_DATE
      Convenience instance for ISO 8601 date format. Format "yyyy-MM-dd".

    • ISO_TIME

      public static final DateFormat ISO_TIME
      Convenience instance for ISO 8601 time format. Format "HH:mm:ss".

    • ISO_DATETIME

      public static final DateFormat ISO_DATETIME
      Convenience instance for ISO 8601 date time combination. Format "yyyy-MM-dd HH:mm:ss".

    • ISO_DATETIME_TIMEDESIGNATOR

      public static final DateFormat ISO_DATETIME_TIMEDESIGNATOR
      Convenience instance for ISO 8601 date time combination with time designator of T. Format "yyyy-MM-ddTHH:mm:ss".

    • US_DATE

      public static final DateFormat US_DATE
      Convenience instance for US date format. Format "yyyy/MM/dd".

    • US_TIME

      public static final DateFormat US_TIME
      Convenience instance for US time format. Format "HH:mm:ss". (Same as ISO_TIME).

    • US_DATETIME

      public static final DateFormat US_DATETIME
      Convenience instance for US date time combination. Format "yyyy/MM/dd HH:mm:ss".

    • YYYYMMDD

      public static final DateFormat YYYYMMDD
      Convenience instance for format "yyyyMMdd". Basically this is the ISO_DATE DateFormat without the separators.

    • DD_MM_YYYY

      public static final DateFormat DD_MM_YYYY
      Convenience instance for format "dd-MM-yyyy".

    • DD_MM_YYYY_HH_MM_SS

      public static final DateFormat DD_MM_YYYY_HH_MM_SS
      Convenience instance for format "dd-MM-yyyy HH:mm:ss".

    • DD_MM_YYYY_HH_MM_SS_SSS

      public static final DateFormat DD_MM_YYYY_HH_MM_SS_SSS
      Convenience instance for format "dd-MM-yyyy HH:mm:ss,SSS".

    • DD_MM_YYYY_HH_MM

      public static final DateFormat DD_MM_YYYY_HH_MM
      Convenience instance for format "dd-MM-yyyy HH:mm".

  • Constructor Details

    • DateFormat

      public DateFormat(IDateSymbol[] symbols)
      Constructor for new DateFormat.
      Parameters:
      symbols - Array of Symbol instances to use when formatting a Date object or parsing a date string.
      Throws:
      IllegalArgumentException - if the passed symbols array is null.
      IllegalArgumentException - if the passed symbols array contains a null pointer.

  • Method Details

    • getInstance

      public static DateFormat getInstance(String pattern)
      Get an instance of DateFormat based on a string representation of the pattern. Note: use constructor for better performance.
      Parameters:
      pattern - The string representation of the pattern.
      Returns:
      An instance of DateFormat which should never be null
      Throws:
      PatternException - When the pattern could not be parsed.

    • registerSymbol

      protected static IDateSymbol registerSymbol(IDateSymbol s)

    • format

      public String format(Date date)
      Formats the specified Date object according to the symbols used to construct this DateFormat instance. This method uses an internally synchronized buffer, so concurrent access from parallel threads is safe.
      • Dates are always formatted using the (proleptic) Gregorian calendar rules. Before 17.0, dates before 1582-10-15 where formatted using the Julian calendar rules.
      • The system default timezone is used (Java only).
      Parameters:
      date - Date object to be formatted.
      Returns:
      String containing the formatted date as defined by the constructor.
      Throws:
      IllegalArgumentException - if the passed Date object is null.

    • parse

      public Date parse(String dateString)
      Parses the specified date string and returns a Date object that represents the date in the dateString parameter.
      • Date Strings are always interpreted using the (proleptic) Gregorian calendar rules. Before 17.0, date Strings before 1582-10-15 where interpreted using the Julian calendar rules
      • The system default timezone is used (Java only).
      Parameters:
      dateString - String to be interpreted as a date.
      Returns:
      Date object representing the date/time specified in the dateString parameter.
      Throws:
      IllegalArgumentException - if the date string passed is null.
      ParseException - if the date string is empty.
      ParseException - if for some reason the date string is deemed invalid.

    • getSymbols

      public IDateSymbol[] getSymbols()
      This method returns the array of symbols of this date formatter.
      Returns:
      Array of symbols.

    • toString

      public String toString()
      Overrides:
      toString in class Object