Well geez, there you go. My google fu obviously failed me, I definitely did not come across this yet another Date Formatting library in the Java Standard Library.

Why isn't all this garbage just bundled into the Date class? It seems to me that among the many things somebody might want to do on a date, converting the String representation might be one of them.

okay here's what I'm talking about. From the API docs on Date

toGMTString() - *Deprecated.* As of JDK version 1.1, replaced by DateFormat.format(Date date), using a GMT TimeZone.

toLocaleString() - *Deprecated.* As of JDK version 1.1, replaced by DateFormat.format(Date date).

toString() - Converts this Date object to a String of the form: dow mon dd hh:mm:ss zzz yyyy

All either deprecated or useless (dow mon dd hh:mm:ss zzz yyyy? really?). And the documentation doesn't point to the better classes to do what I want.

Okay, so what's a DateFormat?

DateFormat is an abstract class for date/time formatting subclasses which formats and parses dates or time in a language-independent manner.

Okay that sounds promising, of course they're admitting they don't have the concept of a "Date Format" object type since it's all just static stuff, so shouldn't all this just be in the Date class? That feels weird.

Wait there's a DateFormatter, that sounds promising, it's all verby sounding.

DateFormatter is an InternationalFormatter that does its formatting by way of an instance of java.text.DateFormat.

Well what the hell is an InternationalFormatter? And down the rabbit hole I went.

I did eventually figure it out. But it was so inelegant and stupid I felt ashamed to have it in my code. If I had read one more line in the DateFormatter doc I suppose I could have found SimpleDateFormat, but the bizarre complexity about converting formats was already so mind bendingly dumb.

This is stupid and obtuse design, overly parsing the problem and unnecessarily separating what should be connected pieces of the puzzle.

Solution (needs revision, but this would be a useful point to start a discussion):

Classes

Date - a representation of a specific date and time down to millionths of a second resolution

methods:

add, sub Dates - returns Duration

add,sub Duration, returns Dates

one of the constructors takes a String that ostensibly contains a Date of some sort, and a format String to parse it, throws exception if the date isn't valid

setOutPutFormat - takes a Format string and the next call toString() emits on that format.

all the get, set hour minute day year methods so you can pick it apart change pieces as you want

setOutPutCalendar - changes the Date to whatever recognized calendar system (Chinese, Arabic, Hebrew, etc.), setOutPutFormat is context aware of this

all the timezone stuff

after and before

get/set 2 digit year

Date comparison methods like isBefore(Date) to see if another Date object is before or after this one

Done. All of Date, DateFormat and SimpleDateFormat is there, problems solved

Duration - an representation of a time Duration (6 days, 7 minutes, 14 second), and since all time intervals are durations, that's it.

Methods:

Constructor can be an ISO 8601 String for Duration or two Date objects representing the beginning and end of a duration. Since Date objects should have their own timezone and locals, the magic black box of this class should figure out the duration for me. It's not my problem to sort this out. If the begin and end dates produce a negative duration that's cool because now I have a countdown.

Duration comparison methods, like isWithin(Duration) to check if another duration object is within this one or isWithin(Date) to see if a Date is within the duration or isLongerthan(Duration)

Duration math like add/subtract other durations from the begin and end of the Duration

Done.