Package 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
`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
`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.
`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.
`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.
`java.lang.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​(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

#### 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 java.util.TimeZone getTimeZone()

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

Returns:
  The Time Zone.

#### setTimeZone

    public void setTimeZone​(java.util.TimeZone timeZone)

Set the Time Zone to use when converting dates.

Parameters:
  `timeZone` - The Time Zone.

#### getLocale

    public java.util.Locale getLocale()

Return the Locale for the Converter (or `null` if none specified).

Returns:
  The locale to use for conversion

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

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

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

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

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