updated: Jun 17 2008
*Time is an illusion. Lunchtime doubly so. (Douglas Adams)
Sorry, documentation is not yet complete and does not provide sufficient information. Please refer to test cases, javadoc and sources for more details.
If you need more info on this particular subject, do not hesitate to demand more documentation.
The Julian day or Julian day number (JDN) is the integer number of days that have elapsed since noon Greenwich Mean Time (UT or TT) Monday, January 1, 4713 BC. The Julian Date (JD) is the number of days (with decimal fraction of the day) that have elapsed since the same epoch. JDs are the recommended way how to specify time in astronomy. The beauty of JD lays in the fact that it is very easy to work with time ranges and rolling dates, since just basic math operations are used: addition and subtraction.
JDateTime tracks time using JD, with precision set up to 1 millisecond. Besides accuracy, it provides also a developer-friendly interface, so it is easy to work with all kind of time-related operations.
JDateTime can be created in various ways: by specifying desired date and/or time, or passing a reference to some date/time related JDK class.
JDateTime provides many methods for adding a specific amount of time to current date/time. Each time unit can be set individually, however, it is possible to add time for various units at once.
jdt.add(1, 2, 3, 4, 5, 6.6); // add 1 year, 2 months, 3 days, 4 hours... jdt.add(0, 120, 0); // add 120 months jdt.addMonth(-120); // go back 120 months jdt.addHour(1234); // add 1234 hours jdt.getHour(); // get hours
As said for initialization, JDateTime may be created from various JDK date/time relate classes. Of course, it is possible to convert JDateTime back to JDK date/time classes, too. Besides creating new classes, JDateTime may read and store date/time information in existing instances of date/time classes.
Calendar c = jdt.convertToCalendar(); jdt.storeTo(gc); // stores date/time information in GregorianCalendar instance java.util.Date d = jdt.convertToDate(); dt.loadFrom(sqlDate); // loads date/time information from java.sql.Date
Special focus is set on string conversion. JDateTime allows developers to specify custom date format for string conversion using patterns. Default formatter enhances patterns specified by ISO 8601. It is easy to create new formatter, and, soon, new one will be added, that uses JDK-friendly patterns.
JDateTime jdt = new JDateTime(1975, 1, 1); jdt.getJulianDate().toString(); // 2442413.5 jdt.toString(); // 1975-01-01 00:00:00.000 (default format) jdt.toString("YYYY.MM.DD"); // 1975.01.01 jdt.toString("MM: MML (MMS)"); // 01: January (Jan) jdt.toString("DD is D: DL (DS)");// 01 is 3: Wednesday (Wed) jdt.toString("DDD / WW / WWW"); // 028 / 05 / W05
JDateTime also knows how to set time form string, using a specified format and ignoring all non-recognized characters:
jdt.fromString("2003-11-24 23:18:38.173"); // using default format jdt.fromString("2003-4-3");
Since date/time manipulation may be used very often, all JDateTime settings can be set on global (i.e. static) level. All default values can be changed for all JDateTime usages.
JDateTime knows about time zones and works exactly in the same way as GregorianCalendar.
JDateTime is able to work with various week definitions. Default is standard one.