Package org.apache.commons.beanutils2.converters

# Class DateTimeConverter<D>

java.lang.Object
org.apache.commons.beanutils2.converters.AbstractConverter<D>
org.apache.commons.beanutils2.converters.DateTimeConverter<D>

Type Parameters:
  `D` - The default value type.

All Implemented Interfaces:
  `Converter<D>`

Direct Known Subclasses:
  `CalendarConverter`, `DateConverter`, `LocalDateConverter`, `LocalDateTimeConverter`, `OffsetDateTimeConverter`, `SqlDateConverter`, `SqlTimeConverter`, `SqlTimestampConverter`, `ZonedDateTimeConverter`

public abstract class DateTimeConverter<D> extends AbstractConverter<D>
`Converter` implementation that handles conversion to and from date/time objects.

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

- `Date`
- `Calendar`
- `LocalDate`
- `LocalDateTime`
- `OffsetDateTime`
- `ZonedDateTime`
- `Date`
- `Time`
- `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(TimeZone)` method.

Since:
  1.8.0

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DateTimeConverter()`
  Constructs a Date/Time Converter that throws a `ConversionException` if an error occurs.
  `DateTimeConverter(D defaultValue)`
  Constructs a Date/Time Converter that returns a default value if an error occurs.

- ## Method Summary

  Modifier and Type
  Method
  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)`
  Gets a `DateFormat` for the Locale.
  `Locale`
  `getLocale()`
  Gets the Locale for the Converter (or `null` if none specified).
  `String[]`
  `getPatterns()`
  Gets the date format patterns used to convert dates to/from a `String` (or `null` if none specified).
  `TimeZone`
  `getTimeZone()`
  Gets the Time Zone to use when converting dates (or `null` if none specified.
  `void`
  `setLocale(Locale locale)`
  Sets the Locale for the Converter.
  `void`
  `setPattern(String pattern)`
  Sets a date format pattern to use to convert dates to/from a `String`.
  `void`
  `setPatterns(String[] patterns)`
  Sets the date format patterns to use to convert dates to/from a `String`.
  `void`
  `setTimeZone(TimeZone timeZone)`
  Sets 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.beanutils2.converters.AbstractConverter

  `conversionException, convert, convertArray, getDefault, getDefaultType, handleError, handleMissing, isUseDefault, setDefaultValue, toLowerCase, toString, toTrim`

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

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

- ## Constructor Details

  - ### DateTimeConverter

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

  - ### DateTimeConverter

    public DateTimeConverter(D defaultValue)
    Constructs 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 Details

  - ### convertToString

    protected String convertToString(Object value)
    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<D>`
    Parameters:
      `value` - The input value to be converted
    Returns:
      the converted String value.
    Throws:
      `IllegalArgumentException` - 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:

    - `Date`
    - `Calendar`
    - `LocalDate`
    - `LocalDateTime`
    - `OffsetDateTime`
    - `ZonedDateTime`
    - `Date`
    - `Time`
    - `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<D>`
    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)
    Gets 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.

  - ### getLocale

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

  - ### getPatterns

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

  - ### getTimeZone

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

  - ### setLocale

    public void setLocale(Locale locale)
    Sets the Locale for the Converter.
    Parameters:
      `locale` - The Locale.

  - ### setPattern

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

  - ### setPatterns

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

  - ### setTimeZone

    public void setTimeZone(TimeZone timeZone)
    Sets 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`

  - ### toString

    public String toString()
    Provide a String representation of this date/time converter.
    Overrides:
      `toString` in class `AbstractConverter<D>`
    Returns:
      A String representation of this date/time converter