javax.faces.convert

## Class DateTimeConverter

- java.lang.Object
- - javax.faces.convert.DateTimeConverter

- All Implemented Interfaces:
    PartialStateHolder, StateHolder, Converter

      public class DateTimeConverter
      extends Object
      implements Converter, PartialStateHolder

  `Converter` implementation for `java.util.Date` values.

  The `getAsObject()` method parses a String into a `java.util.Date`, according to the following algorithm:

  - If the specified String is null, return a `null`. Otherwise, trim leading and trailing whitespace before proceeding.
  - If the specified String - after trimming - has a zero length, return `null`.
  - If the `locale` property is not null, use that `Locale` for managing parsing. Otherwise, use the `Locale` from the `UIViewRoot`.
  - If a `pattern` has been specified, its syntax must conform the rules specified by `java.text.SimpleDateFormat`. Such a pattern will be used to parse, and the `type`, `dateStyle`, and `timeStyle` properties will be ignored.
  - If a `pattern` has not been specified, parsing will be based on the `type` property, which expects a date value, a time value, or both. Any date and time values included will be parsed in accordance to the styles specified by `dateStyle` and `timeStyle`, respectively.
  - If a `timezone` has been specified, it must be passed to the underlying `DateFormat` instance. Otherwise the "GMT" timezone is used.
  - In all cases, parsing must be non-lenient; the given string must strictly adhere to the parsing format.

  The `getAsString()` method expects a value of type `java.util.Date` (or a subclass), and creates a formatted String according to the following algorithm:

  - If the specified value is null, return a zero-length String.
  - If the specified value is a String, return it unmodified.
  - If the `locale` property is not null, use that `Locale` for managing formatting. Otherwise, use the `Locale` from the `UIViewRoot`.
  - If a `timezone` has been specified, it must be passed to the underlying `DateFormat` instance. Otherwise the "GMT" timezone is used.
  - If a `pattern` has been specified, its syntax must conform the rules specified by `java.text.SimpleDateFormat`. Such a pattern will be used to format, and the `type`, `dateStyle`, and `timeStyle` properties will be ignored.
  - If a `pattern` has not been specified, formatting will be based on the `type` property, which includes a date value, a time value, or both into the formatted String. Any date and time values included will be formatted in accordance to the styles specified by `dateStyle` and `timeStyle`, respectively.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONVERTER_ID` The standard converter id for this converter.
    `static String` | `DATE_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Date` fails.
    `static String` | `DATETIME_ID` The message identifier of the `FacesMessage` to be created if the conversion to `DateTime` fails.
    `static String` | `STRING_ID` The message identifier of the `FacesMessage` to be created if the conversion of the `DateTime` value to `String` fails.
    `static String` | `TIME_ID` The message identifier of the `FacesMessage` to be created if the conversion to `Time` fails.

    - ### Fields inherited from interface javax.faces.convert.Converter

      `DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE_PARAM_NAME`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateTimeConverter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearInitialState()` Reset the PartialStateHolder to a non-delta tracking state.
    `Object` | `getAsObject(FacesContext context, UIComponent component, String value)` Convert the specified string value, which is associated with the specified `UIComponent`, into a model data object that is appropriate for being stored during the Apply Request Values phase of the request processing lifecycle.
    `String` | `getAsString(FacesContext context, UIComponent component, Object value)` Convert the specified model object value, which is associated with the specified `UIComponent`, into a String that is suitable for being included in the response generated during the Render Response phase of the request processing lifeycle.
    `String` | `getDateStyle()` Return the style to be used to format or parse dates.
    `Locale` | `getLocale()` Return the `Locale` to be used when parsing or formatting dates and times.
    `String` | `getPattern()` Return the format pattern to be used when formatting and parsing dates and times.
    `String` | `getTimeStyle()` Return the style to be used to format or parse times.
    `TimeZone` | `getTimeZone()` Return the `TimeZone` used to interpret a time value.
    `String` | `getType()` Return the type of value to be formatted or parsed.
    `boolean` | `initialStateMarked()` Return `true` if delta state changes are being tracked, otherwise `false`
    `boolean` | `isTransient()` If true, the Object implementing this interface must not participate in state saving or restoring.
    `void` | `markInitialState()` The runtime must ensure that the `PartialStateHolder.markInitialState()` method is called on each instance of this interface in the view at the appropriate time to indicate the component is in its initial state.
    `void` | `restoreState(FacesContext context, Object state)` Perform any processing required to restore the state from the entries in the state Object.
    `Object` | `saveState(FacesContext context)` Gets the state of the instance as a `Serializable` Object.
    `void` | `setDateStyle(String dateStyle)` Set the style to be used to format or parse dates.
    `void` | `setLocale(Locale locale)` Set the `Locale` to be used when parsing or formatting dates and times.
    `void` | `setPattern(String pattern)` Set the format pattern to be used when formatting and parsing dates and times.
    `void` | `setTimeStyle(String timeStyle)` Set the style to be used to format or parse times.
    `void` | `setTimeZone(TimeZone timeZone)` Set the `TimeZone` used to interpret a time value.
    `void` | `setTransient(boolean transientFlag)` Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
    `void` | `setType(String type)` Set the type of value to be formatted or parsed.

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

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

- - ### Field Detail

    - #### CONVERTER_ID

          public static final String CONVERTER_ID

      The standard converter id for this converter.

      See Also:
        Constant Field Values

    - #### DATE_ID

          public static final String DATE_ID

      The message identifier of the `FacesMessage` to be created if the conversion to `Date` fails. The message format string for this message may optionally include the following placeholders:

      - `{0}` replaced by the unconverted value.
      - `{1}` replaced by an example value.
      - `{2}` replaced by a `String` whose value is the label of the input component that produced this message.
      See Also:
        Constant Field Values

    - #### TIME_ID

          public static final String TIME_ID

      The message identifier of the `FacesMessage` to be created if the conversion to `Time` fails. The message format string for this message may optionally include the following placeholders:

      - `{0}` replaced by the unconverted value.
      - `{1}` replaced by an example value.
      - `{2}` replaced by a `String` whose value is the label of the input component that produced this message.
      See Also:
        Constant Field Values

    - #### DATETIME_ID

          public static final String DATETIME_ID

      The message identifier of the `FacesMessage` to be created if the conversion to `DateTime` fails. The message format string for this message may optionally include the following placeholders:

      - `{0}` replaced by the unconverted value.
      - `{1}` replaced by an example value.
      - `{2}` replaced by a `String` whose value is the label of the input component that produced this message.
      See Also:
        Constant Field Values

    - #### STRING_ID

          public static final String STRING_ID

      The message identifier of the `FacesMessage` to be created if the conversion of the `DateTime` value to `String` fails. The message format string for this message may optionally include the following placeholders:

      - `{0}` relaced by the unconverted value.
      - `{1}` replaced by a `String` whose value is the label of the input component that produced this message.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DateTimeConverter

          public DateTimeConverter()

  - ### Method Detail

    - #### getDateStyle

          public String getDateStyle()

      Return the style to be used to format or parse dates. If not set, the default value, `default`, is returned.

    - #### setDateStyle

          public void setDateStyle(String dateStyle)

      Set the style to be used to format or parse dates. Valid values are `default`, `short`, `medium`, `long`, and `full`. An invalid value will cause a `ConverterException` when `getAsObject()` or `getAsString()` is called.

      Parameters:
        `dateStyle` - The new style code

    - #### getLocale

          public Locale getLocale()

      Return the `Locale` to be used when parsing or formatting dates and times. If not explicitly set, the `Locale` stored in the `UIViewRoot` for the current request is returned.

    - #### setLocale

          public void setLocale(Locale locale)

      Set the `Locale` to be used when parsing or formatting dates and times. If set to `null`, the `Locale` stored in the `UIViewRoot` for the current request will be utilized.

      Parameters:
        `locale` - The new `Locale` (or `null`)

    - #### getPattern

          public String getPattern()

      Return the format pattern to be used when formatting and parsing dates and times.

    - #### setPattern

          public void setPattern(String pattern)

      Set the format pattern to be used when formatting and parsing dates and times. Valid values are those supported by `java.text.SimpleDateFormat`. An invalid value will cause a `ConverterException` when `getAsObject()` or `getAsString()` is called.

      Parameters:
        `pattern` - The new format pattern

    - #### getTimeStyle

          public String getTimeStyle()

      Return the style to be used to format or parse times. If not set, the default value, `default`, is returned.

    - #### setTimeStyle

          public void setTimeStyle(String timeStyle)

      Set the style to be used to format or parse times. Valid values are `default`, `short`, `medium`, `long`, and `full`. An invalid value will cause a `ConverterException` when `getAsObject()` or `getAsString()` is called.

      Parameters:
        `timeStyle` - The new style code

    - #### getTimeZone

          public TimeZone getTimeZone()

      Return the `TimeZone` used to interpret a time value. If not explicitly set, the default time zone of `GMT` returned.

    - #### setTimeZone

          public void setTimeZone(TimeZone timeZone)

      Set the `TimeZone` used to interpret a time value.

      Parameters:
        `timeZone` - The new time zone

    - #### getType

          public String getType()

      Return the type of value to be formatted or parsed. If not explicitly set, the default type, `date` is returned.

    - #### setType

          public void setType(String type)

      Set the type of value to be formatted or parsed. Valid values are `both`, `date`, or `time`. An invalid value will cause a `ConverterException` when `getAsObject()` or `getAsString()` is called.

      Parameters:
        `type` - The new date style

    - #### getAsObject

          public Object getAsObject(FacesContext context,
                           UIComponent component,
                           String value)

      Description copied from interface: `Converter`

      Convert the specified string value, which is associated with the specified `UIComponent`, into a model data object that is appropriate for being stored during the Apply Request Values phase of the request processing lifecycle.

      Specified by:
        `getAsObject` in interface `Converter`
      Parameters:
        `context` - `FacesContext` for the request being processed
        `component` - `UIComponent` with which this model object value is associated
        `value` - String value to be converted (may be `null`)
      Returns:
        `null` if the value to convert is `null`, otherwise the result of the conversion
      Throws:
        `ConverterException` - if conversion cannot be successfully performed
        `NullPointerException` - if `context` or `component` is `null`

    - #### getAsString

          public String getAsString(FacesContext context,
                           UIComponent component,
                           Object value)

      Description copied from interface: `Converter`

      Convert the specified model object value, which is associated with the specified `UIComponent`, into a String that is suitable for being included in the response generated during the Render Response phase of the request processing lifeycle.

      Specified by:
        `getAsString` in interface `Converter`
      Parameters:
        `context` - `FacesContext` for the request being processed
        `component` - `UIComponent` with which this model object value is associated
        `value` - Model object value to be converted (may be `null`)
      Returns:
        a zero-length String if value is `null`, otherwise the result of the conversion
      Throws:
        `ConverterException` - if conversion cannot be successfully performed
        `NullPointerException` - if `context` or `component` is `null`

    - #### saveState

          public Object saveState(FacesContext context)

      Description copied from interface: `StateHolder`

      Gets the state of the instance as a `Serializable` Object.

      If the class that implements this interface has references to instances that implement StateHolder (such as a `UIComponent` with event handlers, validators, etc.) this method must call the `StateHolder.saveState(javax.faces.context.FacesContext)` method on all those instances as well. This method must not save the state of children and facets. That is done via the `StateManager`

      This method must not alter the state of the implementing object. In other words, after executing this code:

      `

           Object state = component.saveState(facesContext);

      `

      `component` should be the same as before executing it.

      The return from this method must be `Serializable`

      Specified by:
        `saveState` in interface `StateHolder`

    - #### restoreState

          public void restoreState(FacesContext context,
                          Object state)

      Description copied from interface: `StateHolder`

      Perform any processing required to restore the state from the entries in the state Object.

      If the class that implements this interface has references to instances that also implement StateHolder (such as a `UIComponent` with event handlers, validators, etc.) this method must call the `StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object)` method on all those instances as well.

      If the `state` argument is `null`, take no action and return.

      Specified by:
        `restoreState` in interface `StateHolder`

    - #### isTransient

          public boolean isTransient()

      Description copied from interface: `StateHolder`

      If true, the Object implementing this interface must not participate in state saving or restoring.

      Specified by:
        `isTransient` in interface `StateHolder`

    - #### setTransient

          public void setTransient(boolean transientFlag)

      Description copied from interface: `StateHolder`

      Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.

      Specified by:
        `setTransient` in interface `StateHolder`
      Parameters:
        `transientFlag` - boolean pass `true` if this Object will not participate in state saving or restoring, otherwise pass `false`.

    - #### markInitialState

          public void markInitialState()

      Description copied from interface: `PartialStateHolder`

      The runtime must ensure that the `PartialStateHolder.markInitialState()` method is called on each instance of this interface in the view at the appropriate time to indicate the component is in its initial state. The implementor of the interface must ensure that `PartialStateHolder.initialStateMarked()` returns `true` from the time `markInitialState()` is called until `PartialStateHolder.clearInitialState()` is called, after which time `initialStateMarked()` must return `false`. Also, during the time that the instance returns `true` from `initialStateMarked()`, the implementation must return only the state that has changed in its implementation of `StateHolder.saveState(javax.faces.context.FacesContext)`.

      Specified by:
        `markInitialState` in interface `PartialStateHolder`

    - #### initialStateMarked

          public boolean initialStateMarked()

      Description copied from interface: `PartialStateHolder`

      Return `true` if delta state changes are being tracked, otherwise `false`

      Specified by:
        `initialStateMarked` in interface `PartialStateHolder`

    - #### clearInitialState

          public void clearInitialState()

      Description copied from interface: `PartialStateHolder`

      Reset the PartialStateHolder to a non-delta tracking state.

      Specified by:
        `clearInitialState` in interface `PartialStateHolder`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.