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:
null
. Otherwise, trim leading and trailing
whitespace before proceeding.null
.locale
property is not null,
use that Locale
for managing parsing. Otherwise, use the
Locale
from the UIViewRoot
.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.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.timezone
has been specified, it must be passed to the
underlying DateFormat
instance. Otherwise the "GMT"
timezone is used.The getAsString()
method expects a value of type
java.util.Date
(or a subclass), and creates a formatted
String according to the following algorithm:
locale
property is not null,
use that Locale
for managing formatting. Otherwise, use the
Locale
from the UIViewRoot
.timezone
has been specified, it must be passed
to the underlying DateFormat
instance. Otherwise
the "GMT" timezone is used.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.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.Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CONVERTER_ID
The standard converter id for this converter.
|
static java.lang.String |
DATE_ID
The message identifier of the
FacesMessage to be created if
the conversion to Date fails. |
static java.lang.String |
DATETIME_ID
The message identifier of the
FacesMessage to be created if
the conversion to DateTime fails. |
static java.lang.String |
STRING_ID
The message identifier of the
FacesMessage to be created if
the conversion of the DateTime value to
String fails. |
static java.lang.String |
TIME_ID
The message identifier of the
FacesMessage to be created if
the conversion to Time fails. |
DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE_PARAM_NAME
Constructor and Description |
---|
DateTimeConverter() |
Modifier and Type | Method and 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 |
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 |
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.
|
public static final java.lang.String CONVERTER_ID
The standard converter id for this converter.
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.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.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.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.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.
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.
dateStyle
- The new style codepublic 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.
Locale
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.
locale
- The new Locale
(or null
)public java.lang.String getPattern()
Return the format pattern to be used when formatting and parsing dates and times.
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.
pattern
- The new format patternpublic java.lang.String getTimeStyle()
Return the style to be used to format or parse times. If not set,
the default value, default
, is returned.
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.
timeStyle
- The new style codepublic java.util.TimeZone getTimeZone()
Return the TimeZone
used to interpret a time value.
If not explicitly set, the default time zone of GMT
returned.
TimeZone
public void setTimeZone(java.util.TimeZone timeZone)
Set the TimeZone
used to interpret a time value.
timeZone
- The new time zonepublic java.lang.String getType()
Return the type of value to be formatted or parsed.
If not explicitly set, the default type, date
is returned.
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.
type
- The new date stylepublic java.lang.Object getAsObject(FacesContext context, UIComponent component, java.lang.String value)
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.
getAsObject
in interface Converter
context
- FacesContext
for the request being processedcomponent
- UIComponent
with which this model object
value is associatedvalue
- String value to be converted (may be null
)null
if the value to convert is null
,
otherwise the result of the conversionConverterException
- if conversion cannot be successfully
performedjava.lang.NullPointerException
- if context
or
component
is null
public java.lang.String getAsString(FacesContext context, UIComponent component, java.lang.Object value)
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.
getAsString
in interface Converter
context
- FacesContext
for the request being processedcomponent
- UIComponent
with which this model object
value is associatedvalue
- Model object value to be converted
(may be null
)null
,
otherwise the result of the conversionConverterException
- if conversion cannot be successfully
performedjava.lang.NullPointerException
- if context
or
component
is null
public java.lang.Object saveState(FacesContext context)
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
saveState
in interface StateHolder
context
- the Faces context.public void restoreState(FacesContext context, java.lang.Object state)
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.
restoreState
in interface StateHolder
context
- the Faces context.state
- the state.public boolean isTransient()
StateHolder
If true, the Object implementing this interface must not participate in state saving or restoring.
isTransient
in interface StateHolder
true
if transient, false
otherwise.public void setTransient(boolean transientFlag)
StateHolder
Denotes whether or not the Object implementing this interface must or must not participate in state saving or restoring.
setTransient
in interface StateHolder
transientFlag
- boolean pass true
if this
Object will not
participate in state saving or restoring, otherwise pass
false
.public void markInitialState()
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)
.
markInitialState
in interface PartialStateHolder
public boolean initialStateMarked()
PartialStateHolder
Return true
if delta state changes are being tracked, otherwise
false
initialStateMarked
in interface PartialStateHolder
true
if the initial state is marked, false
otherwise.public void clearInitialState()
PartialStateHolder
Reset the PartialStateHolder to a non-delta tracking state.
clearInitialState
in interface PartialStateHolder