Date Management in Java

Considering how crucial date representation and computation is to so many of the sorts of commercial transactions that computers manage, you'd expect computers to be better at handling them. Contrary to reasonable expectation though, date representation, parsing, and storage have been a thorn in the side of programmers since the dawn of computers. In the early days of computing, when space was a very scarce resource, programmers stored dates as six-digit numeric strings — two digits for the year, two for the month, and two for the day. The values themselves were stored as strings, so that string sorting and comparison routines would work correctly on these dates, although date arithmetic was difficult. Worse was the decision to store (on disk!) dates using two-digit years. Sorting and comparison worked just fine as long as the dates themselves occurred before 12/31/99; anything after would be interpreted as the year 1900. I worked as a developer at a life insurance company in the mid 90's; the Y2K bug was already causing problems there, since they carried life insurance policies — on people still living — that dated back to 1899.

If you want to do any sort of arithmetic on dates — adding them or comparing them — you need a canonical form to represent them in. Americans and Europeans can't even agree on whether the month should come before they day, and most computer-friendly date formats put the year first so that pure-text sorting will work correctly. To avoid a repeat of the Y2K problem, modern computer systems get away from the concept (and the problems associated with the concept) of days, months and years and instead assign each date its own unique integer code. Such a code has three varying aspects - the granularity, the range, and the starting point. The granularity refers to which points in time get their own codes. Earlier coding-based systems had second-based granularity — every second in time that they were capable or representing was assigned its own unique code. The granulariy, of course, directly impacted the range. An n-bit processor can deal with 2ⁿ unique integer values without loss of precision, so the range that could be represented in this scheme is 2ⁿ/granularity.

C programs used a 32-bit integer and assigned each value to a unique second (not millisecond). This meant that there were 2³² unique seconds that could be represented. This works out to:

232 = 4,294,967,296 seconds
232 / 60 = 71,582,788 minutes
232 / 60 / 60 = 1,193,046 hours
232 / 60 / 60 / 24 = 49,710 days
232 / 60 / 60 / 24 / 365 = 136 years

There's a problem with this, though - what about all of the dates before Jan 1, 1970? There's quite a bit of historical information of interest that occurred before 1970. To make maximal use of their 136-year range, C programmers instead consider the 32-bit counter to be a signed integer; the value 0 is still Jan 1, 1970, but negative numbers represent dates prior to that. This means that, following the canonical standard, C dates can represent any date in the range Dec 13, 1901 - Jan 18, 2038. (Meaning that those life insurance policies from 1899 still caused problems).

Incidentally, this is why I don't worry too much about retirement. The Y2038 problem that will occur when the old 32-bit counters reach their end of life will be even bigger than the Y2K problem, and nastier to fix. I'll turn 65 in the year 2039 — and since I know how to fix Y2038 problems, I plan on billing $300/hour and working 60-hours a week for the three or four years leading up to retirement. Assuming, that is, that the computer that keeps track of my bank account doesn't crash due to Y2038 problems...

Java implementers foresaw the Y2038 problem and gave dates in java a range of 2⁶⁴, and a granularity of one millisecond (one one- thousandth of a second). That means that java can represent 2⁶⁴ unique milliseconds. That works out to an astronomical-seeming 18,446,744,073,709,551,616 values. This represents:

264 / 1000 = 18,446,744,073,709,551.616 seconds
264 / 1000 / 60 = 307,445,734,561,825 minutes
264 / 1000 / 60 / 60 = 5,124,095,576,030 hours
264 / 1000 / 60 / 60 / 24 = 213,503,982,334 days
264 / 1000 / 60 / 60 / 24 / 365 = 584,942,417 years

So, if the code 0 represents January 1, 1970, you'd expect this snippet:

Date d = new Date( 0L );  // initialize a date from a long integer code
System.out.println( d );

Wed Dec 31 18:00:00 CST 1969

Wait, what? Isn't 0 supposed to be January 1, 1970? Well, it is... but in which time zone? The JVM will go ahead and translate dates into your local time zone for you — since I'm 6 hours behind GMT, I see 6 PM on Dec. 31, 1969. This suggests that "zero time" in Java is midnight, January 1, 1970, in GMT (Greenwich Mean Time).

GMT is the timezone that longitude 0 falls in. In the 1800's, naval pilots divided the Earth into 360 equal vertical slices called longitudes and 360 horizontal slices called latitudes so that points on the Earth's surface could be roughly described in a standard way. Since the earth has a stable axis, it made perfect sense to standardize the 0 latitude as the equator. However, there's no logical standard for the 0 longitude. For some time, the 0 longitude varied from one country to the next (usually being the longitude that the capital of the reporters home country fell in). In 1884, the International Meridian Conference established London (particularly, Greenwich village) as the location of the standard 0 longitude.

So far, so good. Assigning each millisecond in a 584-million-year range makes date arithmetic and sorting simple — computers are pretty good at numeric operations. However, computers still need to interface with people, who don't typically work well with 64-bit integers. (Do you know your 64-bit integer birthdate? Mine is 171781200000.) So any date system has to be able to convert from the year-month-day, hour-month-second format that humans are used to into the canonical 64-bit long integer format. This turns out to be quite a bit more difficult than it sounds. It's easy enough to convert seconds to canonical time — just divide by 1000. Minutes? Divide by 60,000. Hours? Divide by 3,600,000. Days? Divide by 86,400,000. Months? Hmmm... well, that depends on which month. (I spent some time looking at this last January if you're curious). Since this conversion is complex, and must take into account a lot of little details such as leap years, Java includes a conversion from year/month/day to canonical format in the java.util.Date class. You can instantiate a Date with a three-integer constructor which will convert to the canonical 64-bit standard representation. It does so, that is, under the assumption that what you want is a Western-style date relative to the year 1900, in the timezone of the currently running system. To support proper internationalization, Sun/Oracle would prefer that you instead use the java.util.Calendar class to specify the timezone and locale, and create dates from that. So, instead of saying:

Date d = new Date( 111, 3, 24 ); // 3 = April; 0-based months.

Listing 1: Simple Date createion

For 4/24/2011 (the date of my first blog entry, if you're curious), you should instead say:

Calendar c = Calendar.getInstance();
c.set( Calendar.YEAR, 2011 );
c.set( Calendar.MONTH, 3 );
c.set( Calendar.DAY_OF_MONTH, 24 );
Date d = c.getTime();

Listing 2: "Correct" date creation

Although this is more i18n friendly (give getInstance a Locale and it will take into account locale-specific settings), this does involve the instantiation of two objects rather than just one. Each call to Calendar.getInstance returns a unique object; it's not a singleton class. A few quick experiments indicate that listing 2, while easier to internationalize, is about three times slower than listing 1.

So, given the three principal components (year, month and day) of a "human- friendly" date, it's a simple matter to convert, although you see quite a few date input boxes in interactive applications that look like Figure 1:

Figure 1: Not very user-friendly date input form

DateFormat fmt = DateFormat.getInstance();

fmt.parse( "4/24/2011" );
fmt.parse( "4/24/11" );
fmt.parse( "2011-04-24" );
fmt.parse( "2011-4-24" );
fmt.parse( "Apr 24, 2011" );
fmt.parse( "April 24, 2011" );

fmt.parse( "4/24/11 12:00 AM" );

fmt.parse( "4/24/11 12:00:00 AM" );
fmt.parse( "4/24/11 12:00AM" );
fmt.parse( "4/24/11 12:00" );
fmt.parse( "4-24-11 12:00 AM" );
fmt.parse( "12:00 4/24/11" );

Table 1: JDK 1.6 locales and date formats

One thing to be careful about with DateFormat and its subclasses such as SimpleDateFormat is that, for some odd reason, they're not thread-safe. If two threads try to to use the same instance to parse (or even format) dates concurrently, behavior is undefined. This is not an idle warning: I ran some tests and found that about 75% of the time, two threads invoking a shared SimpleDateFormat threw nonsensical exceptions such as:

Exception in thread "Thread-2" java.lang.NumberFormatException: multiple points
  at sun.misc.FloatingDecimal.readJavaFormatString(FloatingDecimal.java:1082)
  at java.lang.Double.parseDouble(Double.java:510)
  at java.text.DigitList.getDouble(DigitList.java:151)
  at java.text.DecimalFormat.parse(DecimalFormat.java:1302)
  at java.text.SimpleDateFormat.subParse(SimpleDateFormat.java:1589)
  at java.text.SimpleDateFormat.parse(SimpleDateFormat.java:1311)
  at java.text.DateFormat.parse(DateFormat.java:335)
  at DateTest$1.run(DateTest.java:48)
  at java.lang.Thread.run(Thread.java:680)

Exception in thread "Thread-2" java.lang.NumberFormatException: For input string: ""
  at java.lang.NumberFormatException.forInputString(NumberFormatException.java:48)
  at java.lang.Long.parseLong(Long.java:431)
  at java.lang.Long.parseLong(Long.java:468)
  at java.text.DigitList.getLong(DigitList.java:177)
  at java.text.DecimalFormat.parse(DecimalFormat.java:1297)
  at java.text.SimpleDateFormat.subParse(SimpleDateFormat.java:1934)
  at java.text.SimpleDateFormat.parse(SimpleDateFormat.java:1311)
  at java.text.DateFormat.parse(DateFormat.java:335)
  at DateTest$1.run(DateTest.java:48)
  at java.lang.Thread.run(Thread.java:680)

Exception in thread "Thread-1" java.lang.NumberFormatException: For input string: ".2233E2.2233E2"
  at sun.misc.FloatingDecimal.readJavaFormatString(FloatingDecimal.java:1222)
  at java.lang.Double.parseDouble(Double.java:510)
  at java.text.DigitList.getDouble(DigitList.java:151)
  at java.text.DecimalFormat.parse(DecimalFormat.java:1302)
  at java.text.SimpleDateFormat.subParse(SimpleDateFormat.java:1934)
  at java.text.SimpleDateFormat.parse(SimpleDateFormat.java:1311)
  at java.text.DateFormat.parse(DateFormat.java:335)
  at DateTest$1.run(DateTest.java:48)
  at java.lang.Thread.run(Thread.java:680)

• Fri Apr 23 00:00:00 CDT 2011
• Mon Oct 24 00:00:00 CST 1200
• Fri Apr 24 00:00:00 CST 1917
• Sun Apr 24 00:00:00 CST 1197

The easiest solution is to just create a new SimpleDateFormat for each thread; if you're feeling particularly lazy, instantiate a new one just before you need to parse a date, and let the garbage collector pick it up after the parsing function returns. Conventional wisdom suggests that this is a major performance drain — however, in benchmarking tests I've run on several systems suggests that instantiating a SimpleDateFormat every time you need one is only about 2-3 times slower than trying to share one. Depending on the platform, this is probably in the 1/1,000,000 of a second (microsecond) range, so I don't worry too much about it. I've seen developers do some pretty funky things with ThreadLocal storage to try to beat this and share a single instance across multiple threads, but the application requirements rarely warrant this. (Remember — good enough is good engineering).

In reality, if you're really pinched for performance, though, you should completely forego DateFormat and its subclasses and just do some simple date parsing yourself. The code in listing 3 is about twice as fast as SimpleDateFormat.parse, even when shared.

StringTokenizer tok = new StringTokenizer( in, "-" );
Date d = new Date( Integer.parseInt( tok.nextToken() ) - 1900,
        Integer.parseInt( tok.nextToken() ) - 1,
        Integer.parseInt( tok.nextToken() ) );

Listing 3: Fast fixed-format date parsing

Add a comment:

Completely off-topic or spam comments will be removed at the discretion of the moderator.

You may preserve formatting (e.g. a code sample) by indenting with four spaces preceding the formatted line(s)

I'm the author of the book "Implementing SSL/TLS Using Cryptography and PKI". Like the title says, this is a from-the-ground-up examination of the SSL protocol that provides security, integrity and privacy to most application-level internet protocols, most notably HTTP. I include the source code to a complete working SSL implementation, including the most popular cryptographic algorithms (DES, 3DES, RC4, AES, RSA, DSA, Diffie-Hellman, HMAC, MD5, SHA-1, SHA-256, and ECC), and show how they all fit together to provide transport-layer security.

Joshua Davies

Past Posts

• April 30, 2021: A Date Picker Control in Vanilla Javascript
• March 31, 2021: A Web Admin Console for Redis, Part Three
• January 27, 2021: A Web Admin Console for Redis, Part Two
• December 21, 2020: A Web Admin Console for Redis, Part One
• November 30, 2020: What is Procmail and why is it using up all my memory?
• September 30, 2020: Minimal Drag and Drop Support in Javascript
• August 31, 2020: Covariance and Contravariance in Generic Types
• July 31, 2020: How Spread Out Are the Floating Point Numbers?
• June 25, 2020: ERD Diagramming Tool, Part Three
• April 30, 2020: ERD Diagramming Tool, Part Two
• March 31, 2020: ERD Diagramming Tool, Part One
• February 28, 2020: MathJax and "t.setAttribute is not a function"
• December 30, 2019: Solving Systems of Equations with Python
• October 30, 2019: Linear Regression with and without numpy
• September 30, 2019: Reading a Parquet file outside of Spark
• August 30, 2019: UML Diagrams with MetaUML
• July 30, 2019: Clustering in Python
• June 25, 2019: A Walkthrough of a TLS 1.3 Handhsake
• May 31, 2019: A DataType Printer in Java
• April 30, 2019: A Simple HTTP Server in Java, Part 3 - Cookies and Keep Alives
• March 28, 2019: A Simple HTTP Server in Java, Part 2 - POST and SSL
• February 28, 2019: A Simple HTTP Server in Java
• January 29, 2019: Angular CLI Behind the Scenes, Part Two
• September 30, 2018: Angular CLI Behind the Scenes, Part One
• August 31, 2018: Into the MMIX MOR Instruction
• July 24, 2018: Undoing Percentage Changes in your Head
• June 30, 2018: Generating Langford Pairs in Scala
• May 25, 2018: Reflections on Three Years of Reading Knuth
• April 30, 2018: java.lang.NoSuchMethodError: org.junit.vintage. engine.descriptor.RunnerTestDescriptor. getAllDescendants
• March 30, 2018: An Excel Spreadsheet for the Academy Awards
• February 28, 2018: Git for Subversion Users
• January 31, 2018: The Evolution of AngularJS
• December 31, 2017: Numerical Integration in Python
• October 31, 2017: Gradle for Java Developers
• September 29, 2017: Reflections on another year of reading Knuth
• August 30, 2017: SSL OCSP Exchange
• July 27, 2017: A walk-through of an SSL certificate exchange
• June 30, 2017: A walk-through of an SSL key exchange
• May 31, 2017: A walk-through of the SSL handshake
• March 31, 2017: A walk-through of the TCP handshake
• February 28, 2017: The TLS Handshake at a High Level
• January 31, 2017: A Walk-through of a JWT Verification
• August 31, 2016: Reflections on a year of reading Knuth
• July 29, 2016: Matching a private key to a public key
• June 30, 2016: A Completely Dissected GZIP File
• May 31, 2016: Automatic Guitar Tablature Generator, Part 2
• April 28, 2016: Automatic Guitar Tablature Generator, Part 1
• March 31, 2016: Import an encrypted private key into a Java Key Store
• February 26, 2016: Import a private key into a Java Key Store
• January 31, 2016: Debian Linux on MacBook Pro
• December 29, 2015: Is Computer Science necessary or useful for programmers?
• November 30, 2015: Client certificate authentication vs. password authentication
• October 28, 2015: A Utility for Viewing Java Keystore Contents
• September 29, 2015: Debugging jQuery with Chrome's Developer Tools
• August 26, 2015: Getting Perl, MySQL and Apache to all work together on Mac OS/X
• July 30, 2015: Extract certificates from Java Key Stores for use by CURL
• June 29, 2015: Using the Chrome web developer tools, Part 9: The Console Tab
• May 28, 2015: Using the Chrome web developer tools, Part 8: The Audits Tab
• April 30, 2015: Using the Chrome web developer tools, Part 7: The Resources Tab
• March 30, 2015: Using the Chrome web developer tools, Part 6: The Memory Profiler Tab
• February 27, 2015: Using the Chrome web developer tools, Part 5: The CPU Profiler Tab
• January 31, 2015: Using the Chrome web developer tools, Part 4: The Timeline Tab
• December 31, 2014: Using the Chrome web developer tools, Part 3: The Sources Tab
• October 31, 2014: Using the Chrome web developer tools, Part 2: The Network Tab
• September 30, 2014: Using the Chrome web developer tools, Part 1: The Elements Tab
• August 11, 2014: Unable to find valid certification path to requested target
• June 30, 2014: Sort by a Hierarchy
• May 29, 2014: OpenSSL Tips and Tricks
• April 25, 2014: Heartbleed: What the Heck Happened
• February 28, 2014: Replace Microsoft Money with a Spreadsheet
• January 29, 2014: An Illustrated Guide to the BEAST Attack
• December 21, 2013: Where does GCC look to find its header files?
• October 24, 2013: Planning a Subversion import
• August 28, 2013: Compile and test an iOS app from the command line
• July 31, 2013: The Hidden Costs of Software Reuse
• June 26, 2013: Beware of mvn war:inplace
• May 29, 2013: Block Font Design Using Javascript
• April 4, 2013: Parsing a POM file using only SED
• February 22, 2013: Inside the PDF File Format
• December 31, 2012:How and why rotation matrices work
• November 27, 2012:Date Management in Java
• October 21, 2012: Installing Debian Without a Network
• August 14, 2012: My Review of Matt Neuburg's "Programming iOS 5"
• July 16, 2012: An example OAuth 1.0 Handshake and mini-library
• May 23, 2012: A Javascript one-liner to display cookie values
• April 27, 2012: How SSL Certificates Use Digital Signatures
• March 29, 2012: A breakdown of a GIF decoder
• February 15, 2012: The design and implementation of LZW (the GIF compression algorithm)
• January 16, 2012: Calculate the day of week of any date... in your head
• December 4, 2011: Understanding CRC32
• October 29, 2011: Efficient Huffman Decoding
• October 4, 2011: Extract a private key from a Gnu Keyring file
• September 5, 2011: From Make to Ant to Maven
• July 18, 2011: A bottom-up look at the Apache configuration file
• July 6, 2011: Fun with the HTML 5 Canvas Tag
• Jun 16, 2011: Pain and disfiguration upon all comment spammers
• May 31, 2011: Use of RSSI and Time-of-Flight Wireless Signal Characteristics for Location Tracking
• May 7, 2011: Implementing SSL
• Apr 24, 2011: Dissecting the GZIP format