You will be redirected to our new website in 5 seconds...
If you are not automatically taken to our new web site,
please click on the hyperlink :
build: 309
updated: Jun 17 2008 Logo

freebsd  Support this project

home Home | download | home Contact | SourceForge | File Releases releases | News news |  
*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.

JDateTime 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.

  • Devloper-very-friendly :)
  • In production since 2005
  • Based on proven astronomical algorithms


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.

Time travel

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
String conversion

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

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.

Time Zones

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.