org.apache.commons.beanutils.converters

## Class DateTimeConverter

- java.lang.Object
- - org.apache.commons.beanutils.converters.AbstractConverter
  - - org.apache.commons.beanutils.converters.DateTimeConverter

- All Implemented Interfaces:
    Converter
  Direct Known Subclasses:
    CalendarConverter, DateConverter, SqlDateConverter, SqlTimeConverter, SqlTimestampConverter

      public abstract class DateTimeConverter
      extends AbstractConverter

  `Converter` implementaion 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
  Version:
    $Id$

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateTimeConverter()` Construct a Date/Time Converter that throws a `ConversionException` if an error occurs.
    `DateTimeConverter(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 and Description
    --- | ---
    `protected String` | `convertToString(Object value)` Convert an input Date/Calendar object into a String.
    `protected <T> T` | `convertToType(Class<T> targetType, Object value)` Convert the input object into a Date object of the specified type.
    `protected DateFormat` | `getFormat(Locale locale, TimeZone timeZone)` Return a `DateFormat`for the Locale.``
    `Locale` | `getLocale()` Return the Locale for the Converter (or `null` if none specified).
    `String[]` | `getPatterns()` Return the date format patterns used to convert dates to/from a `java.lang.String` (or `null` if none specified).
    `TimeZone` | `getTimeZone()` Return the Time Zone to use when converting dates (or `null` if none specified.
    `void` | `setLocale(Locale locale)` Set the Locale for the Converter.
    `void` | `setPattern(String pattern)` Set a date format pattern to use to convert dates to/from a `java.lang.String`.
    `void` | `setPatterns(String[] patterns)` Set the date format patterns to use to convert dates to/from a `java.lang.String`.
    `void` | `setTimeZone(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.
    `String` | `toString()` Provide a String representation of this date/time converter.

    - ### Methods inherited from class org.apache.commons.beanutils.converters.AbstractConverter

      `conversionException, convert, convertArray, getDefault, getDefaultType, handleError, handleMissing, isUseDefault, setDefaultValue`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DateTimeConverter

          public DateTimeConverter()

      Construct a Date/Time Converter that throws a `ConversionException` if an error occurs.

    - #### DateTimeConverter

          public DateTimeConverter(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

    - #### 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`

    - #### getTimeZone

          public TimeZone getTimeZone()

      Return the Time Zone to use when converting dates (or `null` if none specified.
      Returns:
        The Time Zone.

    - #### setTimeZone

          public void setTimeZone(TimeZone timeZone)

      Set the Time Zone to use when converting dates.
      Parameters:
        `timeZone` - The Time Zone.

    - #### getLocale

          public Locale getLocale()

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

    - #### setLocale

          public void setLocale(Locale locale)

      Set the Locale for the Converter.
      Parameters:
        `locale` - The Locale.

    - #### setPattern

          public void setPattern(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`

    - #### getPatterns

          public 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`

    - #### setPatterns

          public void setPatterns(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`

    - #### convertToString

          protected String convertToString(Object value)
                                    throws 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:
        `Throwable` - if an error occurs converting to a String

    - #### convertToType

          protected <T> T convertToType(Class<T> targetType,
                                        Object value)
                                 throws 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:
        `Exception` - if conversion cannot be performed successfully

    - #### getFormat

          protected DateFormat getFormat(Locale locale,
                                         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.

    - #### toString

          public 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

Copyright © 2000–2019 The Apache Software Foundation. All rights reserved.