since: VelocityTools - 1.1

 public DateTool() 
{
           
        // do nothing
}

Default constructor.

 public String format(Object obj) 
{
        return format(getFormat(), obj);
}

Converts the specified object to a date and formats it according to the pattern or style returned by #getFormat() .

 public String format(String format,
    Object obj) 
{
        return format(format, obj, getLocale());
}

Converts the specified object to a date and returns a formatted string representing that date in the locale returned by #getLocale() .

 public String format(String format,
    Object obj,
    Locale locale) 
{
        return format(format, obj, locale, getTimeZone());
}

Converts the specified object to a date and returns a formatted string representing that date in the specified Locale .

 public String format(String dateStyle,
    String timeStyle,
    Object obj) 
{
        return format(dateStyle, timeStyle, obj, getLocale());
}

Returns the specified date as a string formatted according to the specified date and/or time styles.

 public String format(String format,
    Object obj,
    Locale locale,
    TimeZone timezone) 
{
        Date date = toDate(obj);
        DateFormat df = getDateFormat(format, locale, timezone);
        if (date == null || df == null)
        {
            return null;
        }
        return df.format(date);
}

Returns a formatted string representing the specified date, Locale , and TimeZone .

The specified format may be a standard style pattern ('full', 'long', 'medium', 'short', or 'default').

You may also specify that you want only the date or time portion be appending '_date' or '_time' respectively to the standard style pattern. (e.g. 'full_date' or 'long_time')

If the format fits neither of these patterns, then the output will be formatted according to the symbols defined by SimpleDateFormat :

Symbol Meaning Presentation Example
------ ------- ------------ -------
G era designator (Text) AD
y year (Number) 1996
M month in year (Text & Number) July & 07
d day in month (Number) 10
h hour in am/pm (1~12) (Number) 12
H hour in day (0~23) (Number) 0
m minute in hour (Number) 30
s second in minute (Number) 55
S millisecond (Number) 978
E day in week (Text) Tuesday
D day in year (Number) 189
F day of week in month (Number) 2 (2nd Wed in July)
w week in year (Number) 27
W week in month (Number) 2
a am/pm marker (Text) PM
k hour in day (1~24) (Number) 24
K hour in am/pm (0~11) (Number) 0
z time zone (Text) Pacific Standard Time
' escape for text (Delimiter)
'' single quote (Literal) '

Examples: "E, MMMM d" will result in "Tue, July 24"
"EEE, M-d (H:m)" will result in "Tuesday, 7-24 (14:12)"

 public String format(String dateStyle,
    String timeStyle,
    Object obj,
    Locale locale) 
{
        return format(dateStyle, timeStyle, obj, locale, getTimeZone());
}

Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.

 public String format(String dateStyle,
    String timeStyle,
    Object obj,
    Locale locale,
    TimeZone timezone) 
{
        Date date = toDate(obj);
        DateFormat df = getDateFormat(dateStyle, timeStyle, locale, timezone);
        if (date == null || df == null)
        {
            return null;
        }
        return df.format(date);
}

Returns the specified date as a string formatted according to the specified Locale and date and/or time styles.

 public String get(String format) 
{
        return format(format, getDate());
}

Returns a formatted string representing the date returned by #getDate() . In its default implementation, this method allows you to retrieve the current date in standard formats by simply doing things like $date.medium or $date.full. If you want only the date or time portion you can specify that along with the standard formats. (e.g. $date.medium_date or $date.short_time) More complex or custom formats can be retrieved by using the full method syntax. (e.g. $date.get('E, MMMM d'))

 public String get(String dateStyle,
    String timeStyle) 
{
        return format(dateStyle, timeStyle, getDate(), getLocale());
}

Returns a formatted string representing the date and/or time given by #getDate() in standard, localized patterns.

 public Calendar getCalendar() 
{
        return Calendar.getInstance(getTimeZone(), getLocale());
}

Returns a Calendar instance created using the timezone and locale returned by getTimeZone() and getLocale(). This allows subclasses to easily override the default locale and timezone used by this tool.

Sub-classes may override this method to return a Calendar instance not based on the system date. Doing so will also cause the getDate(), get(String), get(String,String), and toString() methods to return dates equivalent to the Calendar returned by this method, because those methods return values derived from the result of this method.

 public Date getDate() 
{
        return getCalendar().getTime();
}

Returns a Date derived from the result of #getCalendar

 public DateFormat getDateFormat(String format,
    Locale locale,
    TimeZone timezone) 
{
        if (format == null)
        {
            return null;
        }
        DateFormat df = null;
        // do they want a date instance
        if (format.endsWith("_date"))
        {
            String fmt = format.substring(0, format.length() - 5);
            int style = getStyleAsInt(fmt);
            df = getDateFormat(style, -1, locale, timezone);
        }
        // do they want a time instance?
        else if (format.endsWith("_time"))
        {
            String fmt = format.substring(0, format.length() - 5);
            int style = getStyleAsInt(fmt);
            df = getDateFormat(-1, style, locale, timezone);
        }
        // ok, they either want a custom or date-time instance
        else
        {
            int style = getStyleAsInt(format);
            if (style <  0)
            {
                // we have a custom format
                df = new SimpleDateFormat(format, locale);
                df.setTimeZone(timezone);
            }
            else
            {
                // they want a date-time instance
                df = getDateFormat(style, style, locale, timezone);
            }
        }
        return df;
}

Returns a DateFormat instance for the specified format, Locale , and TimeZone . If the format specified is a standard style pattern, then a date-time instance will be returned with both the date and time styles set to the specified style. If it is a custom format, then a customized SimpleDateFormat will be returned.

 public DateFormat getDateFormat(String dateStyle,
    String timeStyle,
    Locale locale,
    TimeZone timezone) 
{
        int ds = getStyleAsInt(dateStyle);
        int ts = getStyleAsInt(timeStyle);
        return getDateFormat(ds, ts, locale, timezone);
}

Returns a DateFormat instance for the specified date style, time style, Locale , and TimeZone .

 protected DateFormat getDateFormat(int dateStyle,
    int timeStyle,
    Locale locale,
    TimeZone timezone) 
{
        try
        {
            DateFormat df;
            if (dateStyle <  0 && timeStyle <  0)
            {
                // no style was specified, use default instance
                df = DateFormat.getInstance();
            }
            else if (timeStyle <  0)
            {
                // only a date style was specified
                df = DateFormat.getDateInstance(dateStyle, locale);
            }
            else if (dateStyle <  0)
            {
                // only a time style was specified
                df = DateFormat.getTimeInstance(timeStyle, locale);
            }
            else
            {
                df = DateFormat.getDateTimeInstance(dateStyle, timeStyle, 
                                                    locale);
            }
            df.setTimeZone(timezone);
            return df;
        }
        catch (Exception suppressed)
        {
            // let it go...
            return null;
        }
}

Returns a DateFormat instance for the specified time style, date style, Locale , and TimeZone .

 public Integer getDay() 
{
        return getDay(getCalendar());
}

Returns the day (of the month) value of the date returned by #getCalendar() .

NOTE: Unlike java.util.Date, this returns the day of the month. It is equivalent to Date.getDate() and Calendar.get(Calendar.DAY_OF_MONTH). We could not call this method getDate() because that already exists in this class with a different function.

 public Integer getDay(Object date) 
{
        return getValue(Calendar.DAY_OF_MONTH, date);
}

Returns the day (of the month) value for the specified date.

NOTE: Unlike java.util.Date, this returns the day of the month. It is equivalent to Date.getDate() and Calendar.get(Calendar.DAY_OF_MONTH). We could not call this method getDate() because that already exists in this class with a different function.

 public String getFormat() 
{
        return DEFAULT_FORMAT;
}

Return the pattern or style to be used for formatting dates when none is specified. This implementation gives a 'default' date-time format. Subclasses may override this to provide a different default format.

NOTE: At some point in the future it may be feasible to configure this value via the toolbox definition, but at present, it is not possible to specify custom tool configurations there. For now you should just override this in a subclass to have a different default.

 public Locale getLocale() 
{
        return Locale.getDefault();
}

This implementation returns the default locale. Subclasses may override this to return alternate locales. Please note that doing so will affect all formatting methods where no locale is specified in the parameters.

 public Integer getMonth() 
{
        return getMonth(getCalendar());
}

Returns the month value of the date returned by #getCalendar() .

 public Integer getMonth(Object date) 
{
        return getValue(Calendar.MONTH, date);
}

Returns the month value of the specified date.

 protected int getStyleAsInt(String style) 
{
        // avoid needlessly running through all the string comparisons
        if (style == null || style.length() <  4 || style.length()  > 7) {
            return -1;
        }
        if (style.equalsIgnoreCase("full"))
        {
            return DateFormat.FULL;
        }
        if (style.equalsIgnoreCase("long"))
        {
            return DateFormat.LONG;
        }
        if (style.equalsIgnoreCase("medium"))
        {
            return DateFormat.MEDIUM;
        }
        if (style.equalsIgnoreCase("short"))
        {
            return DateFormat.SHORT;
        }
        if (style.equalsIgnoreCase("default"))
        {
            return DateFormat.DEFAULT;
        }
        // ok, it's not any of the standard patterns
        return -1;
}

Checks a string to see if it matches one of the standard DateFormat style patterns: FULL, LONG, MEDIUM, SHORT, or DEFAULT. If it does, it will return the integer constant for that pattern. If not, it will return -1.

 public static final Calendar getSystemCalendar() 
{
        return Calendar.getInstance();
}

 public static final Date getSystemDate() 
{
        return getSystemCalendar().getTime();
}

 public TimeZone getTimeZone() 
{
        return TimeZone.getDefault();
}

This implementation returns the default TimeZone. Subclasses may override this to return alternate timezones. Please note that doing so will affect all formatting methods where no timezone is specified in the parameters.

 public Integer getValue(Object field) 
{
        return getValue(field, getCalendar());
}

Return the specified value of the date returned by #getCalendar() or null if the field is invalid.

 public Integer getValue(Object field,
    Object date) 
{
        if (field == null)
        {
            return null;
        }
        int fieldValue;
        if (field instanceof Integer)
        {
            fieldValue = ((Integer)field).intValue();
        }
        // all the public static field names are upper case
        String fstr = field.toString().toUpperCase();
        try
        {
            Field clsf = Calendar.class.getField(fstr);
            fieldValue = clsf.getInt(Calendar.getInstance());
        }
        catch (Exception e)
        {
            return null;
        }
        return getValue(fieldValue, date);
}

Returns the specified value of the specified date, or null if the field or date is invalid. The field may be an Integer or it may be the name of the field as a String.

 public Integer getValue(int field,
    Object date) 
{
        Calendar cal = toCalendar(date);
        if (cal == null)
        {
            return null;
        }
        return new Integer(cal.get(field));
}

Returns the specified value of the specified date, or null if the field or date is invalid.

 public Integer getYear() 
{
        return getYear(getCalendar());
}

Returns the year value of the date returned by #getCalendar() .

 public Integer getYear(Object date) 
{
        return getValue(Calendar.YEAR, date);
}

Returns the year value of the specified date.

 public Calendar toCalendar(Object obj) 
{
        return toCalendar(obj, getLocale());
}

Converts an object to an instance of Calendar using the locale returned by #getLocale() if necessary.

 public Calendar toCalendar(Object obj,
    Locale locale) 
{
        if (obj == null)
        {
            return null;
        }
        if (obj instanceof Calendar)
        {
            return (Calendar)obj;
        }
        //try to get a date out of it
        Date date = toDate(obj);
        if (date == null)
        {
            return null;
        }
        //convert the date to a calendar
        Calendar cal = Calendar.getInstance(locale);
        cal.setTime(date);
        // HACK: Force all fields to update. see link for explanation of this.
        //http://java.sun.com/j2se/1.4/docs/api/java/util/Calendar.html
        cal.getTime();
        return cal;
}

Converts an object to an instance of Calendar using the locale returned by #getLocale() if necessary.

 public Date toDate(Object obj) 
{
        return toDate(getFormat(), obj, getLocale(), getTimeZone());
}

Converts an object to an instance of Date using the format returned by #getFormat() ,the Locale returned by #getLocale() , and the TimeZone returned by #getTimeZone() if the object is not already an instance of Date, Calendar, or Long.

 public Date toDate(String format,
    Object obj) 
{
        return toDate(format, obj, getLocale(), getTimeZone());
}

Converts an object to an instance of Date using the specified format,the Locale returned by #getLocale() , and the TimeZone returned by #getTimeZone() if the object is not already an instance of Date, Calendar, or Long.

 public Date toDate(String format,
    Object obj,
    Locale locale) 
{
        return toDate(format, obj, locale, getTimeZone());
}

Converts an object to an instance of Date using the specified format and Locale if the object is not already an instance of Date, Calendar, or Long.

 public Date toDate(String format,
    Object obj,
    Locale locale,
    TimeZone timezone) 
{
        if (obj == null)
        {
            return null;
        }
        if (obj instanceof Date)
        {
            return (Date)obj;
        }
        if (obj instanceof Calendar)
        {
            return ((Calendar)obj).getTime();
        }
        if (obj instanceof Number) 
        {
            Date d = new Date();
            d.setTime(((Number)obj).longValue());
            return d;
        }
        try
        {
            //try parsing w/a customized SimpleDateFormat
            DateFormat parser = getDateFormat(format, locale, timezone);
            return parser.parse(String.valueOf(obj));
        }
        catch (Exception e)
        {
            return null;
        }
}

Converts an object to an instance of Date using the specified format, Locale , and TimeZone if the object is not already an instance of Date, Calendar, or Long.

 public String toString() 
{
        return format(getFormat(), getDate());
}