Package org.apache.commons.beanutils.converters

Class DateTimeConverter

  • All Implemented Interfaces:
    Converter
    Direct Known Subclasses:
    CalendarConverter, DateConverter, SqlDateConverter, SqlTimeConverter, SqlTimestampConverter
    public abstract class DateTimeConverter
extends AbstractConverter
    Converter implementation that handles conversion to and from date/time objects.

    This implementation handles conversion for the following date/time types.

    • java.util.Date
    • java.util.Calendar
    • java.sql.Date
    • java.sql.Time
    • java.sql.Timestamp

    String Conversions (to and from)

    This class provides a number of ways in which date/time conversions to/from Strings can be achieved:
    • Using the SHORT date format for the default Locale, configure using:
      • setUseLocaleFormat(true)
    • Using the SHORT date format for a specified Locale, configure using:
      • setLocale(Locale)
    • Using the specified date pattern(s) for the default Locale, configure using:
      • Either setPattern(String) or setPatterns(String[])
    • Using the specified date pattern(s) for a specified Locale, configure using:
      • setPattern(String) or setPatterns(String[]) and...
      • setLocale(Locale)
    • If none of the above are configured the toDate(String) method is used to convert from String to Date and the Dates's toString() method used to convert from Date to String.

    The Time Zone to use with the date format can be specified using the setTimeZone() method.

    Since:
    1.8.0

    • Constructor Summary

      Constructors 
      Constructor Description
      DateTimeConverter()
      Construct a Date/Time Converter that throws a ConversionException if an error occurs.
      DateTimeConverter​(java.lang.Object defaultValue)
      Construct a Date/Time Converter that returns a default value if an error occurs.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.lang.String convertToString​(java.lang.Object value)
      Convert an input Date/Calendar object into a String.
      protected <T> T convertToType​(java.lang.Class<T> targetType, java.lang.Object value)
      Convert the input object into a Date object of the specified type.
      private java.text.DateFormat getFormat​(java.lang.String pattern)
      Create a date format for the specified pattern.
      protected java.text.DateFormat getFormat​(java.util.Locale locale, java.util.TimeZone timeZone)
      Return a DateFormat for the Locale.
      java.util.Locale getLocale()
      Return the Locale for the Converter (or null if none specified).
      java.lang.String[] getPatterns()
      Return the date format patterns used to convert dates to/from a java.lang.String (or null if none specified).
      java.util.TimeZone getTimeZone()
      Return the Time Zone to use when converting dates (or null if none specified.
      private void logFormat​(java.lang.String action, java.text.DateFormat format)
      Log the DateFormat creation.
      private java.util.Calendar parse​(java.lang.Class<?> sourceType, java.lang.Class<?> targetType, java.lang.String value)
      Parse a String date value using the set of patterns.
      private java.util.Calendar parse​(java.lang.Class<?> sourceType, java.lang.Class<?> targetType, java.lang.String value, java.text.DateFormat format)
      Parse a String into a Calendar object using the specified DateFormat.
      void setLocale​(java.util.Locale locale)
      Set the Locale for the Converter.
      void setPattern​(java.lang.String pattern)
      Set a date format pattern to use to convert dates to/from a java.lang.String.
      void setPatterns​(java.lang.String[] patterns)
      Set the date format patterns to use to convert dates to/from a java.lang.String.
      void setTimeZone​(java.util.TimeZone timeZone)
      Set the Time Zone to use when converting dates.
      void setUseLocaleFormat​(boolean useLocaleFormat)
      Indicate whether conversion should use a format/pattern or not.
      private <T> T toDate​(java.lang.Class<T> type, long value)
      Convert a long value to the specified Date type for this Converter.
      private <T> T toDate​(java.lang.Class<T> type, java.lang.String value)
      Default String to Date conversion.
      java.lang.String toString()
      Provide a String representation of this date/time converter.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • patterns

        private java.lang.String[] patterns

      • displayPatterns

        private java.lang.String displayPatterns

      • locale

        private java.util.Locale locale

      • timeZone

        private java.util.TimeZone timeZone

      • useLocaleFormat

        private boolean useLocaleFormat

    • Constructor Detail

      • DateTimeConverter

        public DateTimeConverter()
        Construct a Date/Time Converter that throws a ConversionException if an error occurs.

      • DateTimeConverter

        public DateTimeConverter​(java.lang.Object defaultValue)
        Construct a Date/Time Converter that returns a default value if an error occurs.
        Parameters:
        defaultValue - The default value to be returned if the value to be converted is missing or an error occurs converting the value.

    • Method Detail

      • convertToString

        protected java.lang.String convertToString​(java.lang.Object value)
                                    throws java.lang.Throwable
        Convert an input Date/Calendar object into a String.

        N.B.If the converter has been configured to with one or more patterns (using setPatterns()), then the first pattern will be used to format the date into a String. Otherwise the default DateFormat for the default locale (and style if configured) will be used.

        Overrides:
        convertToString in class AbstractConverter
        Parameters:
        value - The input value to be converted
        Returns:
        the converted String value.
        Throws:
        java.lang.Throwable - if an error occurs converting to a String

      • convertToType

        protected <T> T convertToType​(java.lang.Class<T> targetType,
                              java.lang.Object value)
                       throws java.lang.Exception
        Convert the input object into a Date object of the specified type.

        This method handles conversions between the following types:

        • java.util.Date
        • java.util.Calendar
        • java.sql.Date
        • java.sql.Time
        • java.sql.Timestamp
        It also handles conversion from a String to any of the above types.

        For String conversion, if the converter has been configured with one or more patterns (using setPatterns()), then the conversion is attempted with each of the specified patterns. Otherwise the default DateFormat for the default locale (and style if configured) will be used.

        Specified by:
        convertToType in class AbstractConverter
        Type Parameters:
        T - The desired target type of the conversion.
        Parameters:
        targetType - Data type to which this value should be converted.
        value - The input value to be converted.
        Returns:
        The converted value.
        Throws:
        java.lang.Exception - if conversion cannot be performed successfully

      • getFormat

        protected java.text.DateFormat getFormat​(java.util.Locale locale,
                                         java.util.TimeZone timeZone)
        Return a DateFormat for the Locale.
        Parameters:
        locale - The Locale to create the Format with (may be null)
        timeZone - The Time Zone create the Format with (may be null)
        Returns:
        A Date Format.

      • getFormat

        private java.text.DateFormat getFormat​(java.lang.String pattern)
        Create a date format for the specified pattern.
        Parameters:
        pattern - The date pattern
        Returns:
        The DateFormat

      • getLocale

        public java.util.Locale getLocale()
        Return the Locale for the Converter (or null if none specified).
        Returns:
        The locale to use for conversion

      • getPatterns

        public java.lang.String[] getPatterns()
        Return the date format patterns used to convert dates to/from a java.lang.String (or null if none specified).
        Returns:
        Array of format patterns.
        See Also:
        SimpleDateFormat

      • getTimeZone

        public java.util.TimeZone getTimeZone()
        Return the Time Zone to use when converting dates (or null if none specified.
        Returns:
        The Time Zone.

      • logFormat

        private void logFormat​(java.lang.String action,
                       java.text.DateFormat format)
        Log the DateFormat creation.
        Parameters:
        action - The action the format is being used for
        format - The Date format

      • parse

        private java.util.Calendar parse​(java.lang.Class<?> sourceType,
                                 java.lang.Class<?> targetType,
                                 java.lang.String value)
                          throws java.lang.Exception
        Parse a String date value using the set of patterns.
        Parameters:
        sourceType - The type of the value being converted
        targetType - The type to convert the value to.
        value - The String date value.
        Returns:
        The converted Date object.
        Throws:
        java.lang.Exception - if an error occurs parsing the date.

      • parse

        private java.util.Calendar parse​(java.lang.Class<?> sourceType,
                                 java.lang.Class<?> targetType,
                                 java.lang.String value,
                                 java.text.DateFormat format)
        Parse a String into a Calendar object using the specified DateFormat.
        Parameters:
        sourceType - The type of the value being converted
        targetType - The type to convert the value to
        value - The String date value.
        format - The DateFormat to parse the String value.
        Returns:
        The converted Calendar object.
        Throws:
        ConversionException - if the String cannot be converted.

      • setLocale

        public void setLocale​(java.util.Locale locale)
        Set the Locale for the Converter.
        Parameters:
        locale - The Locale.

      • setPattern

        public void setPattern​(java.lang.String pattern)
        Set a date format pattern to use to convert dates to/from a java.lang.String.
        Parameters:
        pattern - The format pattern.
        See Also:
        SimpleDateFormat

      • setPatterns

        public void setPatterns​(java.lang.String[] patterns)
        Set the date format patterns to use to convert dates to/from a java.lang.String.
        Parameters:
        patterns - Array of format patterns.
        See Also:
        SimpleDateFormat

      • setTimeZone

        public void setTimeZone​(java.util.TimeZone timeZone)
        Set the Time Zone to use when converting dates.
        Parameters:
        timeZone - The Time Zone.

      • setUseLocaleFormat

        public void setUseLocaleFormat​(boolean useLocaleFormat)
        Indicate whether conversion should use a format/pattern or not.
        Parameters:
        useLocaleFormat - true if the format for the locale should be used, otherwise false

      • toDate

        private <T> T toDate​(java.lang.Class<T> type,
                     long value)
        Convert a long value to the specified Date type for this Converter.

        This method handles conversion to the following types:

        • java.util.Date
        • java.util.Calendar
        • java.sql.Date
        • java.sql.Time
        • java.sql.Timestamp
        Type Parameters:
        T - The target type
        Parameters:
        type - The Date type to convert to
        value - The long value to convert.
        Returns:
        The converted date value.

      • toDate

        private <T> T toDate​(java.lang.Class<T> type,
                     java.lang.String value)
        Default String to Date conversion.

        This method handles conversion from a String to the following types:

        • java.sql.Date
        • java.sql.Time
        • java.sql.Timestamp

        N.B. No default String conversion mechanism is provided for java.util.Date and java.util.Calendar type.

        Type Parameters:
        T - The target type
        Parameters:
        type - The date type to convert to
        value - The String value to convert.
        Returns:
        The converted Number value.

      • toString

        public java.lang.String toString()
        Provide a String representation of this date/time converter.
        Overrides:
        toString in class AbstractConverter
        Returns:
        A String representation of this date/time converter