Package javax.faces.convert

Class DateTimeConverter

  • All Implemented Interfaces:
    PartialStateHolder, StateHolder, Converter

    public class DateTimeConverter
extends java.lang.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 or java.time.format.DateTimeFormatter. Which of these two formatters is used depends on the value of type. Such a pattern will be used to parse, and the type, dateStyle, and timeStyle properties will be ignored, unless the value of type is one of the java.time specific values listed in setType(java.lang.String). In this case, DateTimeFormatter.ofPattern(String, Locale) must be called, passing the value of pattern as the first argument and the current Locale as the second argument, and this formatter must be used to parse the incoming value.
    • If a pattern has not been specified, parsing will be based on the type property, which expects a date value, a time value, both, or one of several values specific to classes in java.time as listed in setType(java.lang.String). 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 or java.time.format.DateTimeFormatter. Which of these two formatters is used depends on the value of type. Such a pattern will be used to format, and the type, dateStyle, and timeStyle properties will be ignored, unless the value of type is one of the java.time specific values listed in setType(java.lang.String). In this case, DateTimeFormatter.ofPattern(String, Locale) must be called, passing the value of pattern as the first argument and the current Locale as the second argument, and this formatter must be used to format the outgoing value.
    • If a pattern has not been specified, formatting will be based on the type property, which includes a date value, a time value, both or into the formatted String. Any date and time values included will be formatted in accordance to the styles specified by dateStyle and timeStyle, respectively.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clearInitialState​()
      Reset the PartialStateHolder to a non-delta tracking state.
      java.lang.Object getAsObject​(FacesContext context, UIComponent component, java.lang.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 Process Validations phase of the request processing lifecycle.
      java.lang.String getAsString​(FacesContext context, UIComponent component, java.lang.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.
      java.lang.String getDateStyle​()
      Return the style to be used to format or parse dates.
      java.util.Locale getLocale​()
      Return the Locale to be used when parsing or formatting dates and times.
      java.lang.String getPattern​()
      Return the format pattern to be used when formatting and parsing dates and times.
      java.lang.String getTimeStyle​()
      Return the style to be used to format or parse times.
      java.util.TimeZone getTimeZone​()
      Return the TimeZone used to interpret a time value.
      java.lang.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, java.lang.Object state)
      Perform any processing required to restore the state from the entries in the state Object.
      java.lang.Object saveState​(FacesContext context)
      Gets the state of the instance as a Serializable Object.
      void setDateStyle​(java.lang.String dateStyle)
      Set the style to be used to format or parse dates.
      void setLocale​(java.util.Locale locale)
      Set the Locale to be used when parsing or formatting dates and times.
      void setPattern​(java.lang.String pattern)
      Set the format pattern to be used when formatting and parsing dates and times.
      void setTimeStyle​(java.lang.String timeStyle)
      Set the style to be used to format or parse times.
      void setTimeZone​(java.util.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​(java.lang.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 java.lang.String CONVERTER_ID

        The standard converter id for this converter.

        See Also:
        Constant Field Values

      • DATE_ID

        public static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String getDateStyle​()

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

        Returns:
        the style

      • setDateStyle

        public void setDateStyle​(java.lang.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 java.util.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.

        Returns:
        the Locale

      • setLocale

        public void setLocale​(java.util.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 java.lang.String getPattern​()

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

        Returns:
        the pattern

      • setPattern

        public void setPattern​(java.lang.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 java.lang.String getTimeStyle​()

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

        Returns:
        the time style

      • setTimeStyle

        public void setTimeStyle​(java.lang.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 java.util.TimeZone getTimeZone​()

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

        Returns:
        the TimeZone

      • setTimeZone

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

        Set the TimeZone used to interpret a time value.

        Parameters:
        timeZone - The new time zone

      • getType

        public java.lang.String getType​()

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

        Returns:
        the type

      • setType

        public void setType​(java.lang.String type)

        Set the type of value to be formatted or parsed. Valid values are both, date, time localDate, localDateTime, localTime, offsetTime, offsetDateTime, or zonedDateTime. The values starting with "local", "offset" and "zoned" correspond to Java SE 8 Date Time API classes in package java.time with the name derived by upper casing the first letter. For example, java.time.LocalDate for the value "localDate". An invalid value will cause a ConverterException when getAsObject() or getAsString() is called.

        Parameters:
        type - The new date style

      • getAsObject

        public java.lang.Object getAsObject​(FacesContext context,
                                    UIComponent component,
                                    java.lang.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 Process Validations 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
        java.lang.NullPointerException - if context or component is null

      • getAsString

        public java.lang.String getAsString​(FacesContext context,
                                    UIComponent component,
                                    java.lang.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
        java.lang.NullPointerException - if context or component is null

      • saveState

        public java.lang.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
        Parameters:
        context - the Faces context.
        Returns:
        the saved state.

      • restoreState

        public void restoreState​(FacesContext context,
                         java.lang.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
        Parameters:
        context - the Faces context.
        state - the state.

      • 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
        Returns:
        true if transient, false otherwise.

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

      • 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
        Returns:
        true if the initial state is marked, false otherwise.