com.opensymphony.util
Class DateUtil

java.lang.Object
  extended bycom.opensymphony.util.DateUtil

public class DateUtil
extends java.lang.Object

This class is used to convert Dates to ISO 8601 formatted dates and back. This class is an implementation of the ISO 8601 International Date Format standard. The ISO 8601 helps to alleviate the following problem:

Ever been to a webpage to see that the time-sensitive information you are interested in is dated 03/05/01?

Is this date the 3rd of May 2001 or the 5th of March 2001 or the 1st of May 2003 and does the 01 refer to 2001 in the first two cases?

In order to make the right choice, you must ask yourself some questions :

Which one is it? It could be very important to you.

The Internet is a truly International method of communicating - there are no political or cultural boundaries drawn on the www page you call up - the page could have been stored in the Smithsonian Institute or on a small server in a basement in Ulan Bator, Mongolia. Often, you have no way of telling. So, if anyone in the world can read your page, why not ensure that any date references on that page can be read correctly and unambiguously by that person, by using the ISO 8601:1988 International Date Format?

The basic format is: "CCYYMMDDThhmmsssss±nnn"

Characters used in place of digits or signs
 [Y]  represents a digit used in the time element year
 [M]  represents a digit used in the time element month
 [D]  represents a digit used in the time element day
 [T]  place holder denoting time
 [h]  represents a digit used in the time element hour
 [m]  represents a digit used in the time element minute
 [s]  represents a digit used in the time element second
 [n]  represents digit(s), constituting a positive integer or zero
 [±]  represents a plus sign [+] if in combination with the following element a positive value or zero needs to be represented, or a minus sign [­] if in combination with the following element a negative value needs to be represented.

The expanded format includes formating: "CCYY-MM-DDThh:mm:ss,sss±nnn"

Further there are some date math functions for ISO Dates.

Other Functions

funtions for julian dates

Version:
$Revision: 1.1.1.1 $
Author:
SnowWolf Wagner, Joseph B. Ottinger

Field Summary
static java.text.DateFormatSymbols dateFormatSymbles
           
static java.lang.String ISO_DATE_FORMAT
          Base ISO 8601 Date format yyyyMMdd i.e., 20021225 for the 25th day of December in the year 2002
static java.lang.String ISO_DATE_TIME_FORMAT
          Base ISO 8601 Date format yyyyMMddTHHmmssSSSzzz i.e., 20021225T143212333-500 for the 25th day of December in the year 2002 at 2 pm 32 min 12 secs 333 mills -5 hours from GMT
static java.lang.String ISO_EXPANDED_DATE_FORMAT
          Expanded ISO 8601 Date format yyyy-MM-dd i.e., 2002-12-25 for the 25th day of December in the year 2002
static java.lang.String ISO_EXPANDED_DATE_TIME_FORMAT
          Base ISO 8601 Date format yyyy-MM-ddTHH:mm:ss,SSSzzz i.e., 2002-12-25T14:32:12,333-500 for the 25th day of December in the year 2002 at 2 pm 32 min 12 secs 333 mills -5 hours from GMT
static java.lang.String ISO_EXPANDED_TIME_FORMAT
          Basic ISO 8601 Time format HH:mm:ss,SSSzzz i.e., 14:32:12,333-500 for 2 pm 32 min 12 secs 333 mills -5 hours from GMT 24 hour clock
static java.lang.String ISO_TIME_FORMAT
          Basic ISO 8601 Time format HHmmssSSSzzz i.e., 143212333-500 for 2 pm 32 min 12 secs 333 mills -5 hours from GMT 24 hour clock
 
Constructor Summary
DateUtil()
           
 
Method Summary
static java.lang.String add(java.lang.String isoString, int field, int amount)
          Date Arithmetic function.
static java.lang.String add(java.lang.String isoString, int field, int amount, boolean expanded)
          Date Arithmetic function.
static java.lang.String dateToISO(java.util.Date date)
          non-expanded
static java.lang.String dateToISO(java.util.Date date, boolean expanded)
          Return an ISO date string
static long dateToJulianDay(java.util.Date date)
          Converts java Date to Julian day count A Julian day is defined as the number of days since Jan 1, 1.
static int daysBetween(java.util.Calendar early, java.util.Calendar late)
          Deprecated.  
static int daysBetween(java.util.Date early, java.util.Date late)
          Deprecated.  
static long daysBetween(java.lang.String isoEarly, java.lang.String isoLate, boolean expanded)
          Returns the days between two dates.
static java.util.TimeZone getTimeZoneFromDateTime(java.lang.String date)
           
static java.util.TimeZone getTimeZoneFromDateTime(java.lang.String date, boolean expanded)
           
static boolean isLeapYear(java.lang.String isoString)
           
static boolean isLeapYear(java.lang.String isoString, boolean expanded)
           
static java.util.Date isoToDate(java.lang.String dateString)
          non-expanded
static java.util.Date isoToDate(java.lang.String dateString, boolean expanded)
          Return an ISO date string as a java.util.Date
static java.sql.Date isoToSQLDate(java.lang.String dateString)
          non-expanded
static java.sql.Date isoToSQLDate(java.lang.String dateString, boolean expanded)
          Return an ISO date string as a java.sql.Date
static java.sql.Time isoToTime(java.lang.String dateString)
          non-expanded
static java.sql.Time isoToTime(java.lang.String dateString, boolean expanded)
           
static java.sql.Timestamp isoToTimestamp(java.lang.String dateString)
          non-expanded
static java.sql.Timestamp isoToTimestamp(java.lang.String dateString, boolean expanded)
           
static java.sql.Date julianDayCountToDate(long julian)
          Convert a julian day count to a java sql Date @ midnight
static java.util.Date julianDayToDate(long julian)
          Convert a julian day count to a java util Date @ midnight
static long julianDayToMillis(long julian)
          Converts Julian day to time as milliseconds.
static long millisToJulianDay(long millis)
          Converts time as milliseconds to Julian day count A Julian day is defined as the number of days since Jan 1, 1.
protected static float normalizedJulian(float JD)
           
static java.lang.String roll(java.lang.String isoString, int field, boolean up)
          Time Field Rolling function.
static java.lang.String roll(java.lang.String isoString, int field, boolean up, boolean expanded)
          Time Field Rolling function.
static java.lang.String timestampToISO(java.sql.Timestamp date)
          non-expanded
static java.lang.String timestampToISO(java.sql.Timestamp date, boolean expanded)
           
static java.lang.String timeToISO(java.sql.Time date)
          non-expanded
static java.lang.String timeToISO(java.sql.Time date, boolean expanded)
           
static java.util.Date toDate(float JD)
          Deprecated.  
static float toJulian(java.util.Calendar c)
          Return a Julian date based on the input parameter.
static float toJulian(java.util.Date date)
          Return a Julian date based on the input parameter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ISO_DATE_FORMAT

public static final java.lang.String ISO_DATE_FORMAT
Base ISO 8601 Date format yyyyMMdd i.e., 20021225 for the 25th day of December in the year 2002

See Also:
Constant Field Values

ISO_EXPANDED_DATE_FORMAT

public static final java.lang.String ISO_EXPANDED_DATE_FORMAT
Expanded ISO 8601 Date format yyyy-MM-dd i.e., 2002-12-25 for the 25th day of December in the year 2002

See Also:
Constant Field Values

ISO_TIME_FORMAT

public static final java.lang.String ISO_TIME_FORMAT
Basic ISO 8601 Time format HHmmssSSSzzz i.e., 143212333-500 for 2 pm 32 min 12 secs 333 mills -5 hours from GMT 24 hour clock

See Also:
Constant Field Values

ISO_EXPANDED_TIME_FORMAT

public static final java.lang.String ISO_EXPANDED_TIME_FORMAT
Basic ISO 8601 Time format HH:mm:ss,SSSzzz i.e., 14:32:12,333-500 for 2 pm 32 min 12 secs 333 mills -5 hours from GMT 24 hour clock

See Also:
Constant Field Values

ISO_DATE_TIME_FORMAT

public static final java.lang.String ISO_DATE_TIME_FORMAT
Base ISO 8601 Date format yyyyMMddTHHmmssSSSzzz i.e., 20021225T143212333-500 for the 25th day of December in the year 2002 at 2 pm 32 min 12 secs 333 mills -5 hours from GMT

See Also:
Constant Field Values

ISO_EXPANDED_DATE_TIME_FORMAT

public static final java.lang.String ISO_EXPANDED_DATE_TIME_FORMAT
Base ISO 8601 Date format yyyy-MM-ddTHH:mm:ss,SSSzzz i.e., 2002-12-25T14:32:12,333-500 for the 25th day of December in the year 2002 at 2 pm 32 min 12 secs 333 mills -5 hours from GMT

See Also:
Constant Field Values

dateFormatSymbles

public static final java.text.DateFormatSymbols dateFormatSymbles
Constructor Detail

DateUtil

public DateUtil()
Method Detail

isLeapYear

public static final boolean isLeapYear(java.lang.String isoString,
                                       boolean expanded)
                                throws java.text.ParseException
Parameters:
isoString -
expanded -
Returns:
True id leap year
Throws:
java.text.ParseException

isLeapYear

public static final boolean isLeapYear(java.lang.String isoString)
                                throws java.text.ParseException
Parameters:
isoString -
Returns:
true if is leap year
Throws:
java.text.ParseException

getTimeZoneFromDateTime

public static final java.util.TimeZone getTimeZoneFromDateTime(java.lang.String date,
                                                               boolean expanded)
                                                        throws java.text.ParseException
Throws:
java.text.ParseException

getTimeZoneFromDateTime

public static final java.util.TimeZone getTimeZoneFromDateTime(java.lang.String date)
                                                        throws java.text.ParseException
Throws:
java.text.ParseException

add

public static final java.lang.String add(java.lang.String isoString,
                                         int field,
                                         int amount,
                                         boolean expanded)
                                  throws java.text.ParseException
Date Arithmetic function. Adds the specified (signed) amount of time to the given time field, based on the GregorianCalendar's rules.

Parameters:
isoString -
field -
amount -
expanded - use formating char's
Returns:
ISO 8601 Date String
Throws:
java.text.ParseException

add

public static final java.lang.String add(java.lang.String isoString,
                                         int field,
                                         int amount)
                                  throws java.text.ParseException
Date Arithmetic function. Adds the specified (signed) amount of time to the given time field, based on the GregorianCalendar's rules. no formating char's

Parameters:
isoString -
field -
amount -
Returns:
ISO 8601 Date String
Throws:
java.text.ParseException

dateToISO

public static final java.lang.String dateToISO(java.util.Date date,
                                               boolean expanded)
Return an ISO date string

Parameters:
date -
expanded - use formating char's
Returns:
ISO date String

dateToISO

public static final java.lang.String dateToISO(java.util.Date date)
non-expanded

Parameters:
date -
Returns:
ISO Date String

dateToJulianDay

public static final long dateToJulianDay(java.util.Date date)
Converts java Date to Julian day count A Julian day is defined as the number of days since Jan 1, 1.

Parameters:
date -
Returns:
julian day

daysBetween

public static final int daysBetween(java.util.Date early,
                                    java.util.Date late)
Deprecated.  

Returns the days between two dates. Positive values indicate that the second date is after the first, and negative values indicate, well, the opposite. Relying on specific times is problematic.

Parameters:
early - the "first date"
late - the "second date"
Returns:
the days between the two dates

daysBetween

public static final int daysBetween(java.util.Calendar early,
                                    java.util.Calendar late)
Deprecated.  

Returns the days between two dates. Positive values indicate that the second date is after the first, and negative values indicate, well, the opposite.

Parameters:
early -
late -
Returns:
the days between two dates.

daysBetween

public static final long daysBetween(java.lang.String isoEarly,
                                     java.lang.String isoLate,
                                     boolean expanded)
                              throws java.text.ParseException
Returns the days between two dates. Positive values indicate that the second date is after the first, and negative values indicate, well, the opposite.

Parameters:
isoEarly - the "first date" in ISO DateTime Format
isoLate - the "second date" in ISO Date Time format
Returns:
the days between the two dates
Throws:
java.text.ParseException

isoToDate

public static final java.util.Date isoToDate(java.lang.String dateString,
                                             boolean expanded)
                                      throws java.text.ParseException
Return an ISO date string as a java.util.Date

Parameters:
dateString -
expanded - use formating charaters
Returns:
java.util.Date from the ISO Date in GMT
Throws:
java.text.ParseException

isoToDate

public static final java.util.Date isoToDate(java.lang.String dateString)
                                      throws java.text.ParseException
non-expanded

Parameters:
dateString -
Returns:
ISO java.util.Date
Throws:
java.text.ParseException

isoToSQLDate

public static final java.sql.Date isoToSQLDate(java.lang.String dateString,
                                               boolean expanded)
                                        throws java.text.ParseException
Return an ISO date string as a java.sql.Date

Parameters:
dateString -
expanded - expanded use formating charaters
Returns:
java.util.Date from the ISO Date in GMT
Throws:
java.text.ParseException

isoToSQLDate

public static final java.sql.Date isoToSQLDate(java.lang.String dateString)
                                        throws java.text.ParseException
non-expanded

Parameters:
dateString -
Returns:
java.sql.Date
Throws:
java.text.ParseException

isoToTime

public static final java.sql.Time isoToTime(java.lang.String dateString,
                                            boolean expanded)
                                     throws java.text.ParseException
Parameters:
expanded - expanded use formating charaters
dateString -
Returns:
ISO Date String
Throws:
java.text.ParseException

isoToTime

public static final java.sql.Time isoToTime(java.lang.String dateString)
                                     throws java.text.ParseException
non-expanded

Parameters:
dateString -
Returns:
Time
Throws:
java.text.ParseException

isoToTimestamp

public static final java.sql.Timestamp isoToTimestamp(java.lang.String dateString,
                                                      boolean expanded)
                                               throws java.text.ParseException
Parameters:
expanded - expanded use formating charaters
dateString -
Returns:
ISO Time String
Throws:
java.text.ParseException

isoToTimestamp

public static final java.sql.Timestamp isoToTimestamp(java.lang.String dateString)
                                               throws java.text.ParseException
non-expanded

Parameters:
dateString -
Returns:
Timestamp
Throws:
java.text.ParseException

julianDayCountToDate

public static final java.sql.Date julianDayCountToDate(long julian)
Convert a julian day count to a java sql Date @ midnight

Parameters:
julian - the given Julian day number.
Returns:
java.sql.Date

julianDayToDate

public static final java.util.Date julianDayToDate(long julian)
Convert a julian day count to a java util Date @ midnight

Parameters:
julian - the given Julian day number.
Returns:
java.util.Date

julianDayToMillis

public static final long julianDayToMillis(long julian)
Converts Julian day to time as milliseconds.

Parameters:
julian - the given Julian day number.
Returns:
time as milliseconds.

millisToJulianDay

public static final long millisToJulianDay(long millis)
Converts time as milliseconds to Julian day count A Julian day is defined as the number of days since Jan 1, 1.

Parameters:
millis - the given milliseconds.
Returns:
the Julian day number.

roll

public static final java.lang.String roll(java.lang.String isoString,
                                          int field,
                                          boolean up,
                                          boolean expanded)
                                   throws java.text.ParseException
Time Field Rolling function. Rolls (up/down) a single unit of time on the given time field.

Parameters:
isoString -
field - the time field.
up - Indicates if rolling up or rolling down the field value.
expanded - use formating char's
Throws:
java.text.ParseException - if an unknown field value is given.

roll

public static final java.lang.String roll(java.lang.String isoString,
                                          int field,
                                          boolean up)
                                   throws java.text.ParseException
Time Field Rolling function. Rolls (up/down) a single unit of time on the given time field.

Parameters:
isoString -
field - the time field.
up - Indicates if rolling up or rolling down the field value.
Throws:
java.text.ParseException - if an unknown field value is given.

timeToISO

public static final java.lang.String timeToISO(java.sql.Time date,
                                               boolean expanded)
Parameters:
expanded - expanded use formating charaters
date -
Returns:
ISO Time String

timeToISO

public static final java.lang.String timeToISO(java.sql.Time date)
non-expanded

Parameters:
date -
Returns:
ISO Time String

timestampToISO

public static final java.lang.String timestampToISO(java.sql.Timestamp date,
                                                    boolean expanded)
Parameters:
expanded - expanded use formating charaters
date -
Returns:
ISO Date Time String

timestampToISO

public static final java.lang.String timestampToISO(java.sql.Timestamp date)
non-expanded

Parameters:
date -
Returns:
ISO Date/Time String

toDate

public static final java.util.Date toDate(float JD)
Deprecated.  

Returns the Date from a julian. The Julian date will be converted to noon GMT, such that it matches the nearest half-integer (i.e., a julian date of 1.4 gets changed to 1.5, and 0.9 gets changed to 0.5.)

Parameters:
JD - the Julian date
Returns:
the Gregorian date

toJulian

public static final float toJulian(java.util.Calendar c)
Return a Julian date based on the input parameter. This is based from calculations found at Julian Day Calculations (Gregorian Calendar), provided by Bill Jeffrys.

Parameters:
c - a calendar instance
Returns:
the julian day number

toJulian

public static final float toJulian(java.util.Date date)
Return a Julian date based on the input parameter. This is based from calculations found at Julian Day Calculations (Gregorian Calendar), provided by Bill Jeffrys.

Parameters:
date -
Returns:
the julian day number

normalizedJulian

protected static final float normalizedJulian(float JD)

See www.opensymphony.com for more information.