Code:

     Most Java programmers are well aware that a formatted date string can be produced by handing a long millisecond value to a java.util.Date. For example, sending a millisecond value of 1039977110326 to a Date, and then printing the Date, results in output like Sun Dec 15 13:31:50 EST 2002.

     That's pretty handy, but there are times when we want to print a duration. Say that we tend to forget which day it is, and we'd like to know how long we spent on vacation. So we write a program that captures the current millisecond value, run it just before we leave, and again immediately on our return. Now we can subtract the first value from the second value and we know exactly how many milliseconds we were away!

     Many times that's what we want. We don't really care precisely what value the milliseconds represent, we just want to take a number of samples and compare their relative sizes. For performance tuning, that's perfect; we just want to pick the algorithm with the smallest elapsed millisecond value. Other times though, we'd really like to see something like "Elapsed time was Hours: 4, Minutes: 17, Seconds: 36, Millis: 817" instead of "Elapsed time was 15456817 milliseconds." Unfortunately, the Date class always expects that a millisecond value sent to it represents the number of milliseconds since the Java epoch, namely January 1, 1970, 00:00:00 GMT.

     The OS_MillisConverter class presented here does exactly what we want. Pass it a millisecond value in the constructor, or later to the setMillis( long millisValue ) method. setMillis() extracts and stores all the values from weeks and total days down to the remaining millisecond value. The original millisecond value is available as well.

     At that point, we can retrieve any of the values. We can also get three different formatted results: One method, formatToWeeksAndDays(), returns a String formatted as weeks and days down to milliseconds; another, formatToDaysOnly(), returns a String formatted as days down to milliseconds. So, if we had a value that spanned 37 days, formatToWeeksAndDays() would return "Weeks: 5, Days: 2, Hours:...", while formatToDaysOnly() would return "Days: 37, Hours:...".

     As a side effect of the coding breakdown, formatEndString( boolean bPrintRemaining ) can be directly invoked to return the remainder hours, minutes and so on of the initially passed value. Referring to the output above, formatEndString() would return the value starting with hours. The boolean value informs the method whether all values should be formatted or, instead, to begin formatting at the first element to have a non-zero value. "First", in this case, means in the hierarchy hours, minutes, seconds and milliseconds. Note that formatEndString() returns a StringBuffer rather than a String.

     A main method is included as an exerciser; send it a numeric value representing milliseconds and it will display the formatted Strings from formatToWeeksAndDays(), formatToDaysOnly(), and toString(). Warning: as a developer tester, there is no validation of the input, so send it something parsable to a number or else watch it blow up.

     I did do some performance testing on various methods of extracting the values from the millisecond argument to setMillis(). In my tests against three alternatives, then two, there was less than a quarter-second difference over 100,000 iterations. My feeling is that the quick returns available from the bottom up method should prove best, since I expect the vast majority of values to be less than a minute in duration. Your mileage may vary. Have a good 86400000 milliseconds and beyond!