View Javadoc

1   package org.apache.velocity.tools.generic;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.lang.reflect.Field;
23  import java.text.DateFormat;
24  import java.text.SimpleDateFormat;
25  import java.util.Date;
26  import java.util.Calendar;
27  import java.util.Locale;
28  import java.util.TimeZone;
29  import org.apache.velocity.tools.ConversionUtils;
30  import org.apache.velocity.tools.ToolContext;
31  import org.apache.velocity.tools.config.DefaultKey;
32  
33  /**
34   * Tool for working with {@link Date} and {@link Calendar}
35   * in Velocity templates.  It is useful for accessing and
36   * formatting the "current" date as well as for formatting
37   * arbitrary {@link Date} and {@link Calendar} objects. Also
38   * the tool can be used to retrieve {@link DateFormat} instances
39   * or make conversions to and from various date types.
40   * <p><pre>
41   * Example of formatting the "current" date:
42   *  $date                         -> Oct 19, 2003 9:54:50 PM
43   *  $date.long                    -> October 19, 2003 9:54:50 PM PDT
44   *  $date.medium_time             -> 9:54:50 PM
45   *  $date.full_date               -> Sunday, October 19, 2003
46   *  $date.get('default','short')  -> Oct 19, 2003 9:54 PM
47   *  $date.get('yyyy-M-d H:m:s')   -> 2003-10-19 21:54:50
48   *
49   * Example of formatting an arbitrary date:
50   *  $myDate                        -> Tue Oct 07 03:14:50 PDT 2003
51   *  $date.format('medium',$myDate) -> Oct 7, 2003 3:14:50 AM
52   *
53   * Example tools.xml config (if you want to use this with VelocityView):
54   * &lt;tools&gt;
55   *   &lt;toolbox scope="application"&gt;
56   *     &lt;tool class="org.apache.velocity.tools.generic.DateTool"
57   *              format="yyyy-MM-dd"/&gt;
58   *   &lt;/toolbox&gt;
59   * &lt;/tools&gt;
60   * </pre></p>
61   *
62   * <p>The methods of this tool are highly interconnected, and overriding
63   * key methods provides an easy way to create subclasses that use
64   * a non-default format, calendar, locale, or timezone.</p>
65   *
66   * @author Nathan Bubna
67   * @since VelocityTools 1.0
68   * @version $Revision: 719489 $ $Date: 2008-11-20 22:05:11 -0800 (Thu, 20 Nov 2008) $
69   */
70  @DefaultKey("date")
71  public class DateTool extends FormatConfig
72  {
73      @Deprecated
74      public static final String DEFAULT_FORMAT_KEY = FORMAT_KEY;
75  
76      @Deprecated
77      public static final String DEFAULT_LOCALE_KEY = ToolContext.LOCALE_KEY;
78  
79      /**
80       * The key used for specifying a default timezone via tool configuration.
81       */
82      public static final String TIMEZONE_KEY = "timezone";
83  
84      private TimeZone timezone = TimeZone.getDefault(); 
85  
86      /**
87       * Does the actual configuration. This is protected, so
88       * subclasses may share the same ValueParser and call configure
89       * at any time, while preventing templates from doing so when
90       * configure(Map) is locked.
91       */
92      protected void configure(ValueParser values)
93      {
94          super.configure(values);
95  
96          String tzId = values.getString(TIMEZONE_KEY);
97          if (tzId != null)
98          {
99              setTimeZone(TimeZone.getTimeZone(tzId));
100         }
101     } 
102 
103     protected void setTimeZone(TimeZone timezone)
104     {
105         if (timezone == null)
106         {
107             throw new NullPointerException("timezone may not be null");
108         }
109         this.timezone = timezone;
110     }
111 
112     // ------------------------- system date access ------------------
113 
114     /**
115      * @return the system's current time as the number of milliseconds
116      * elapsed since January 1, 1970, 00:00:00 GMT.
117      */
118     public static final long getSystemTime()
119     {
120         return getSystemCalendar().getTime().getTime();
121     }
122 
123     /**
124      * @return the system's current time as a {@link Date}
125      */
126     public static final Date getSystemDate()
127     {
128         return getSystemCalendar().getTime();
129     }
130 
131 
132     /**
133      * @return the system's current time as a {@link Calendar}
134      */
135     public static final Calendar getSystemCalendar()
136     {
137         return Calendar.getInstance();
138     }
139 
140 
141     // ------------------------- default parameter access ----------------
142 
143     /**
144      * Returns the configured {@link TimeZone}. Default value is
145      * from {@link TimeZone#getDefault()}.
146      *
147      * @return the configured {@link TimeZone}
148      */
149     public TimeZone getTimeZone()
150     {
151         return timezone;
152     }
153 
154     /**
155      * Returns a {@link Date} derived from the result of {@link #getCalendar}
156      *
157      * @return a {@link Date} derived from the result of {@link #getCalendar}
158      */
159     public Date getDate()
160     {
161         return getCalendar().getTime();
162     }
163 
164     /**
165      * Returns a {@link Calendar} instance created using the timezone and
166      * locale returned by getTimeZone() and getLocale().  This allows subclasses
167      * to easily override the default locale and timezone used by this tool.
168      *
169      * <p>Sub-classes may override this method to return a Calendar instance
170      * not based on the system date.
171      * Doing so will also cause the getDate(), get(String), get(String,String),
172      * and toString() methods to return dates equivalent to the Calendar
173      * returned by this method, because those methods return values derived
174      * from the result of this method.</p>
175      *
176      * @return a {@link Calendar} instance created using the results of
177      *         {@link #getTimeZone()} and {@link #getLocale()}.
178      * @see Calendar#getInstance(TimeZone zone, Locale aLocale)
179      */
180     public Calendar getCalendar()
181     {
182         return Calendar.getInstance(getTimeZone(), getLocale());
183     }
184 
185     // ------------------------- date value access ---------------------------
186 
187     /**
188      * Returns the year value of the date returned by {@link #getCalendar()}.
189      *
190      * @since VelocityTools 1.2
191      */
192     public Integer getYear()
193     {
194         return getYear(getCalendar());
195     }
196 
197     /**
198      * Returns the year value of the specified date.
199      *
200      * @since VelocityTools 1.2
201      */
202     public Integer getYear(Object date)
203     {
204         return getValue(Calendar.YEAR, date);
205     }
206 
207     /**
208      * Returns the month value of the date returned by {@link #getCalendar()}.
209      *
210      * @since VelocityTools 1.2
211      */
212     public Integer getMonth()
213     {
214         return getMonth(getCalendar());
215     }
216 
217     /**
218      * Returns the month value of the specified date.
219      *
220      * @since VelocityTools 1.2
221      */
222     public Integer getMonth(Object date)
223     {
224         return getValue(Calendar.MONTH, date);
225     }
226 
227     /**
228      * Returns the day (of the month) value of the date
229      * returned by {@link #getCalendar()}.
230      * <br><br>
231      * NOTE: Unlike java.util.Date, this returns the day of the month.
232      * It is equivalent to Date.getDate() and
233      * Calendar.get(Calendar.DAY_OF_MONTH).  We could not call this method
234      * getDate() because that already exists in this class with a different
235      * function.
236      *
237      * @since VelocityTools 1.2
238      */
239     public Integer getDay()
240     {
241         return getDay(getCalendar());
242     }
243 
244     /**
245      * Returns the day (of the month) value for the specified date.
246      * <br><br>
247      * NOTE: Unlike java.util.Date, this returns the day of the month.
248      * It is equivalent to Date.getDate() and
249      * Calendar.get(Calendar.DAY_OF_MONTH).  We could not call this method
250      * getDate() because that already exists in this class with a different
251      * function.
252      *
253      * @since VelocityTools 1.2
254      */
255     public Integer getDay(Object date)
256     {
257         return getValue(Calendar.DAY_OF_MONTH, date);
258     }
259 
260     /**
261      * Return the specified value of the date returned by
262      * {@link #getCalendar()} or null if the field is invalid.
263      *
264      * @since VelocityTools 1.2
265      */
266     public Integer getValue(Object field)
267     {
268         return getValue(field, getCalendar());
269     }
270 
271     /**
272      * Returns the specified value of the specified date,
273      * or null if the field or date is invalid.  The field may be
274      * an Integer or it may be the name of the field as a String.
275      *
276      * @param field the corresponding Integer value or String name of the desired value
277      * @param date the date/calendar from which the field value will be taken
278      * @since VelocityTools 1.2
279      */
280     public Integer getValue(Object field, Object date)
281     {
282         if (field == null)
283         {
284             return null;
285         }
286 
287         int fieldValue;
288         if (field instanceof Integer)
289         {
290             fieldValue = ((Integer)field).intValue();
291         }
292         // all the public static field names are upper case
293         String fstr = field.toString().toUpperCase();
294         try
295         {
296             Field clsf = Calendar.class.getField(fstr);
297             fieldValue = clsf.getInt(Calendar.getInstance());
298         }
299         catch (Exception e)
300         {
301             return null;
302         }
303         return getValue(fieldValue, date);
304     }
305 
306     /**
307      * Returns the specified value of the specified date,
308      * or null if the field or date is invalid.
309      *
310      * @param field the int for the desired field (e.g. Calendar.MONTH)
311      * @param date the date/calendar from which the field value will be taken
312      * @since VelocityTools 1.2
313      */
314     public Integer getValue(int field, Object date)
315     {
316         Calendar cal = toCalendar(date);
317         if (cal == null)
318         {
319             return null;
320         }
321         return Integer.valueOf(cal.get(field));
322     }
323 
324 
325     // ------------------------- formatting methods ---------------------------
326 
327     /**
328      * Returns a formatted string representing the date returned by
329      * {@link #getDate()}.  In its default implementation, this method
330      * allows you to retrieve the current date in standard formats by
331      * simply doing things like <code>$date.medium</code> or
332      * <code>$date.full</code>.  If you want only the date or time portion
333      * you can specify that along with the standard formats. (e.g.
334      * <code>$date.medium_date</code> or <code>$date.short_time</code>)
335      * More complex or custom formats can be retrieved
336      * by using the full method syntax. (e.g. $date.get('E, MMMM d'))
337      *
338      * @param format the formatting instructions
339      * @return a formatted representation of the date returned by
340      *         {@link #getDate()}
341      * @see #format(String format, Object obj, Locale locale, TimeZone timezone)
342      * @since VelocityTools 1.1
343      */
344     public String get(String format)
345     {
346         return format(format, getDate());
347     }
348 
349     /**
350      * Returns a formatted string representing the date and/or time given by
351      * {@link #getDate()} in standard, localized patterns.
352      *
353      * @param dateStyle the style pattern for the date
354      * @param timeStyle the style pattern for the time
355      * @return a formatted representation of the date returned by
356      *         {@link #getDate()}
357      * @see DateFormat
358      * @see #format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)
359      * @since VelocityTools 1.1
360      */
361     public String get(String dateStyle, String timeStyle)
362     {
363         return format(dateStyle, timeStyle, getDate(), getLocale());
364     }
365 
366 
367     /**
368      * Converts the specified object to a date and formats it according to
369      * the pattern or style returned by {@link #getFormat()}.
370      *
371      * @param obj the date object to be formatted
372      * @return the specified date formatted as a string
373      * @see #format(String format, Object obj, Locale locale, TimeZone timezone)
374      * @since VelocityTools 1.1
375      */
376     public String format(Object obj)
377     {
378         return format(getFormat(), obj);
379     }
380 
381     /**
382      * Converts the specified object to a date and returns
383      * a formatted string representing that date in the locale
384      * returned by {@link #getLocale()}.
385      *
386      * @param format the formatting instructions
387      * @param obj the date object to be formatted
388      * @return a formatted string for this locale representing the specified
389      *         date or <code>null</code> if the parameters are invalid
390      * @see #format(String format, Object obj, Locale locale, TimeZone timezone)
391      */
392     public String format(String format, Object obj)
393     {
394         return format(format, obj, getLocale());
395     }
396 
397     /**
398      * Converts the specified object to a date and returns
399      * a formatted string representing that date in the specified
400      * {@link Locale}.
401      *
402      * @param format the formatting instructions
403      * @param obj the date object to be formatted
404      * @param locale the locale to be used when formatting
405      * @return the given date as a formatted string
406      * @see #format(String format, Object obj, Locale locale, TimeZone timezone)
407      */
408     public String format(String format, Object obj, Locale locale)
409     {
410         return format(format, obj, locale, getTimeZone());
411     }
412 
413     /**
414      * Returns a formatted string representing the specified date,
415      * {@link Locale}, and {@link TimeZone}.
416      *
417      * <p>
418      * The specified format may be a standard style pattern ('full', 'long',
419      * 'medium', 'short', or 'default').
420      * </p>
421      * <p>
422      * You may also specify that you want only the date or time portion be
423      * appending '_date' or '_time' respectively to the standard style pattern.
424      * (e.g. 'full_date' or 'long_time')
425      * </p>
426      * <p>
427      * If the format fits neither of these patterns, then the output
428      * will be formatted according to the symbols defined by
429      * {@link SimpleDateFormat}:
430      * <pre>
431      *   Symbol   Meaning                 Presentation        Example
432      *   ------   -------                 ------------        -------
433      *   G        era designator          (Text)              AD
434      *   y        year                    (Number)            1996
435      *   M        month in year           (Text & Number)     July & 07
436      *   d        day in month            (Number)            10
437      *   h        hour in am/pm (1~12)    (Number)            12
438      *   H        hour in day (0~23)      (Number)            0
439      *   m        minute in hour          (Number)            30
440      *   s        second in minute        (Number)            55
441      *   S        millisecond             (Number)            978
442      *   E        day in week             (Text)              Tuesday
443      *   D        day in year             (Number)            189
444      *   F        day of week in month    (Number)            2 (2nd Wed in July)
445      *   w        week in year            (Number)            27
446      *   W        week in month           (Number)            2
447      *   a        am/pm marker            (Text)              PM
448      *   k        hour in day (1~24)      (Number)            24
449      *   K        hour in am/pm (0~11)    (Number)            0
450      *   z        time zone               (Text)              Pacific Standard Time
451      *   '        escape for text         (Delimiter)
452      *   ''       single quote            (Literal)           '
453      *
454      *   Examples: "E, MMMM d" will result in "Tue, July 24"
455      *             "EEE, M-d (H:m)" will result in "Tuesday, 7-24 (14:12)"
456      * </pre>
457      * </p>
458      *
459      * @param format the custom or standard pattern to be used
460      * @param obj the date to format
461      * @param locale the {@link Locale} to format the date for
462      * @param timezone the {@link TimeZone} to be used when formatting
463      * @return a formatted string representing the specified date or
464      *         <code>null</code> if the parameters are invalid
465      * @since VelocityTools 1.1
466      */
467     public String format(String format, Object obj,
468                          Locale locale, TimeZone timezone)
469     {
470         Date date = toDate(obj);
471         DateFormat df = getDateFormat(format, locale, timezone);
472         if (date == null || df == null)
473         {
474             return null;
475         }
476         return df.format(date);
477     }
478 
479 
480     /**
481      * Returns the specified date as a string formatted according to the
482      * specified date and/or time styles.
483      *
484      * @param dateStyle the style pattern for the date
485      * @param timeStyle the style pattern for the time
486      * @param obj the date to be formatted
487      * @return a formatted representation of the given date
488      * @see #format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)
489      * @since VelocityTools 1.1
490      */
491     public String format(String dateStyle, String timeStyle, Object obj)
492     {
493         return format(dateStyle, timeStyle, obj, getLocale());
494     }
495 
496     /**
497      * Returns the specified date as a string formatted according to the
498      * specified {@link Locale} and date and/or time styles.
499      *
500      * @param dateStyle the style pattern for the date
501      * @param timeStyle the style pattern for the time
502      * @param obj the date to be formatted
503      * @param locale the {@link Locale} to be used for formatting the date
504      * @return a formatted representation of the given date
505      * @see #format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)
506      * @since VelocityTools 1.1
507      */
508     public String format(String dateStyle, String timeStyle,
509                          Object obj, Locale locale)
510     {
511         return format(dateStyle, timeStyle, obj, locale, getTimeZone());
512     }
513 
514     /**
515      * Returns the specified date as a string formatted according to the
516      * specified {@link Locale} and date and/or time styles.
517      *
518      * @param dateStyle the style pattern for the date
519      * @param timeStyle the style pattern for the time
520      * @param obj the date to be formatted
521      * @param locale the {@link Locale} to be used for formatting the date
522      * @param timezone the {@link TimeZone} the date should be formatted for
523      * @return a formatted representation of the given date
524      * @see java.text.DateFormat
525      * @see #format(String dateStyle, String timeStyle, Object obj, Locale locale, TimeZone timezone)
526      * @since VelocityTools 1.1
527      */
528     public String format(String dateStyle, String timeStyle,
529                          Object obj, Locale locale, TimeZone timezone)
530     {
531         Date date = toDate(obj);
532         DateFormat df = getDateFormat(dateStyle, timeStyle, locale, timezone);
533         if (date == null || df == null)
534         {
535             return null;
536         }
537         return df.format(date);
538     }
539 
540 
541     // -------------------------- DateFormat creation methods --------------
542 
543     /**
544      * Returns a {@link DateFormat} instance for the specified
545      * format, {@link Locale}, and {@link TimeZone}.  If the format
546      * specified is a standard style pattern, then a date-time instance
547      * will be returned with both the date and time styles set to the
548      * specified style.  If it is a custom format, then a customized
549      * {@link SimpleDateFormat} will be returned.
550      *
551      * @param format the custom or standard formatting pattern to be used
552      * @param locale the {@link Locale} to be used
553      * @param timezone the {@link TimeZone} to be used
554      * @return an instance of {@link DateFormat}
555      * @see SimpleDateFormat
556      * @see DateFormat
557      * @since VelocityTools 1.1
558      */
559     public DateFormat getDateFormat(String format, Locale locale,
560                                     TimeZone timezone)
561     {
562         return ConversionUtils.getDateFormat(format, locale, timezone);
563     }
564 
565     /**
566      * Returns a {@link DateFormat} instance for the specified
567      * date style, time style, {@link Locale}, and {@link TimeZone}.
568      *
569      * @param dateStyle the date style
570      * @param timeStyle the time style
571      * @param locale the {@link Locale} to be used
572      * @param timezone the {@link TimeZone} to be used
573      * @return an instance of {@link DateFormat}
574      * @see #getDateFormat(int timeStyle, int dateStyle, Locale locale, TimeZone timezone)
575      * @since VelocityTools 1.1
576      */
577     public DateFormat getDateFormat(String dateStyle, String timeStyle,
578                                     Locale locale, TimeZone timezone)
579     {
580         return ConversionUtils.getDateFormat(dateStyle, timeStyle, locale, timezone);
581     }
582 
583     /**
584      * Returns a {@link DateFormat} instance for the specified
585      * time style, date style, {@link Locale}, and {@link TimeZone}.
586      *
587      * @param dateStyle the date style (date will be ignored if this is
588      *        less than zero and the date style is not)
589      * @param timeStyle the time style (time will be ignored if this is
590      *        less than zero and the date style is not)
591      * @param locale the {@link Locale} to be used
592      * @param timezone the {@link TimeZone} to be used
593      * @return an instance of {@link DateFormat} or <code>null</code>
594      *         if an instance cannot be constructed with the given
595      *         parameters
596      * @since VelocityTools 1.1
597      */
598     @Deprecated
599     protected DateFormat getDateFormat(int dateStyle, int timeStyle,
600                                        Locale locale, TimeZone timezone)
601     {
602         return ConversionUtils.getDateFormat(dateStyle, timeStyle, locale, timezone);
603     }
604 
605     /**
606      * Checks a string to see if it matches one of the standard DateFormat
607      * style patterns: FULL, LONG, MEDIUM, SHORT, or DEFAULT.  If it does,
608      * it will return the integer constant for that pattern.  If not, it
609      * will return -1.
610      *
611      * @see DateFormat
612      * @param style the string to be checked
613      * @return the int identifying the style pattern
614      * @since VelocityTools 1.1
615      */
616     @Deprecated
617     protected int getStyleAsInt(String style)
618     {
619         return ConversionUtils.getDateStyleAsInt(style);
620     }
621 
622 
623     // ------------------------- date conversion methods ---------------
624 
625     /**
626      * Converts an object to an instance of {@link Date} using the
627      * format returned by {@link #getFormat()},the {@link Locale} returned
628      * by {@link #getLocale()}, and the {@link TimeZone} returned by
629      * {@link #getTimeZone()} if the object is not already an instance
630      * of Date, Calendar, or Long.
631      *
632      * @param obj the date to convert
633      * @return the object as a {@link Date} or <code>null</code> if no
634      *         conversion is possible
635      */
636     public Date toDate(Object obj)
637     {
638         return toDate(getFormat(), obj, getLocale(), getTimeZone());
639     }
640 
641     /**
642      * Converts an object to an instance of {@link Date} using the
643      * specified format,the {@link Locale} returned by
644      * {@link #getLocale()}, and the {@link TimeZone} returned by
645      * {@link #getTimeZone()} if the object is not already an instance
646      * of Date, Calendar, or Long.
647      *
648      * @param format - the format the date is in
649      * @param obj - the date to convert
650      * @return the object as a {@link Date} or <code>null</code> if no
651      *         conversion is possible
652      * @see #toDate(String format, Object obj, Locale locale)
653      */
654     public Date toDate(String format, Object obj)
655     {
656         return toDate(format, obj, getLocale(), getTimeZone());
657     }
658 
659     /**
660      * Converts an object to an instance of {@link Date} using the
661      * specified format and {@link Locale} if the object is not already
662      * an instance of Date, Calendar, or Long.
663      *
664      * @param format - the format the date is in
665      * @param obj - the date to convert
666      * @param locale - the {@link Locale}
667      * @return the object as a {@link Date} or <code>null</code> if no
668      *         conversion is possible
669      * @see SimpleDateFormat#parse
670      */
671     public Date toDate(String format, Object obj, Locale locale)
672     {
673         return toDate(format, obj, locale, getTimeZone());
674     }
675 
676     /**
677      * Converts an object to an instance of {@link Date} using the
678      * specified format, {@link Locale}, and {@link TimeZone} if the
679      * object is not already an instance of Date, Calendar, or Long.
680      *
681      * @param format - the format the date is in
682      * @param obj - the date to convert
683      * @param locale - the {@link Locale}
684      * @param timezone - the {@link TimeZone}
685      * @return the object as a {@link Date} or <code>null</code> if no
686      *         conversion is possible
687      * @see #getDateFormat
688      * @see SimpleDateFormat#parse
689      */
690     public Date toDate(String format, Object obj,
691                        Locale locale, TimeZone timezone)
692     {
693         return ConversionUtils.toDate(obj, format, locale, timezone);
694     }
695 
696     /**
697      * Converts an object to an instance of {@link Calendar} using the
698      * locale returned by {@link #getLocale()} if necessary.
699      *
700      * @param obj the date to convert
701      * @return the converted date
702      * @see #toCalendar(Object obj, Locale locale)
703      */
704     public Calendar toCalendar(Object obj)
705     {
706         return toCalendar(obj, getLocale());
707     }
708 
709     /**
710      * Converts an object to an instance of {@link Calendar} using the
711      * locale returned by {@link #getLocale()} if necessary.
712      *
713      * @param obj the date to convert
714      * @param locale the locale used
715      * @return the converted date
716      * @see #toDate(String format, Object obj, Locale locale)
717      * @see Calendar
718      */
719     public Calendar toCalendar(Object obj, Locale locale)
720     {
721         if (obj == null)
722         {
723             return null;
724         }
725         if (obj instanceof Calendar)
726         {
727             return (Calendar)obj;
728         }
729         //try to get a date out of it
730         Date date = toDate(obj);
731         if (date == null)
732         {
733             return null;
734         }
735 
736         // if the locale is null, do as the javadoc claims
737         if (locale == null)
738         {
739             locale = getLocale();
740         }
741 
742         //convert the date to a calendar
743         return ConversionUtils.toCalendar(date, locale);
744     }
745 
746 
747     // ------------------------- default toString() implementation ------------
748 
749     /**
750      * @return the result of {@link #getDate()} formatted according to the result
751      *         of {@link #getFormat()}.
752      * @see #format(String format, Object obj)
753      */
754     public String toString()
755     {
756         return format(getFormat(), getDate());
757     }
758 
759 
760 }