DateTimeConverter (Java EE 5)

java.util.Date 值的 Converter 实现。

getAsObject() 方法根据以下算法将 String 解析为 java.util.Date：

• 如果指定的 String 为 null，则返回 null。否则，在继续处理前去除前导空格和尾部的空格。
• 如果指定的 String（去除空格后）长度为 0，则返回 null。
• 如果 locale 属性不为 null，则使用该 Locale 管理解析。否则，使用 UIViewRoot 的 Locale。
• 如果指定了 pattern，则其语法必须遵守 java.text.SimpleDateFormat 指定的规则。此类模式将用于解析，并且将忽略 type、dateStyle 和 timeStyle 属性。
• 如果尚未指定 pattern，则将根据 type 属性进行解析，它应该为日期值或时间值，或者同时包含两者。将根据 dateStyle 和 timeStyle 指定的样式分别对包含的任何日期和时间值进行解析。
• 如果指定了 timezone，则它必须传递给底层 DateFormat 实例。否则，使用 "GMT" 时区。
• 无论是哪种情况，解析必须严格；给定的字符串必须严格遵守解析格式。

getAsString() 方法应该获取类型为 java.util.Date（或子类）的值，并根据以下算法创建格式化 String：

• 如果指定的值为 null，则返回长度为 0 的 String。
• 如果指定的值为 String，则不加修改地返回该值。
• 如果 locale 属性不为 null，则使用该 Locale 管理格式化。否则，使用 UIViewRoot 的 Locale。
• 如果指定了 timezone，则它必须传递给底层 DateFormat 实例。否则，使用 "GMT" 时区。
• 如果指定了 pattern，则其语法必须遵守 java.text.SimpleDateFormat 指定的规则。此类模式将用于格式化，并且将忽略 type、dateStyle 和 timeStyle 属性。
• 如果尚未指定 pattern，则将根据 type 属性进行格式化，这将在格式化的 String 中包含日期值或时间值，或者同时包含两者。将根据 dateStyle 和 timeStyle 指定的样式分别对包含的任何日期和时间值进行格式化。

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.

英文文档：

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

public DateTimeConverter()

英文文档：

DateTimeConverter

public DateTimeConverter()

public String getDateStyle()

返回将用于格式化或解析日期的样式。如果未设置，则返回默认值 default。

英文文档：

getDateStyle

public 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(String dateStyle)

设置将用于格式化或解析日期的样式。有效值有 default、short、medium、long 和 full。当调用 getAsObject() 或 getAsString() 时，无效值将导致 ConverterException。

dateStyle

新样式代码

英文文档：

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

public java.util.Locale getLocale()

返回将在解析或格式化日期和时间时使用的 Locale。如果没有明确设置，则返回存储在当前请求的 javax.faces.component.UIViewRoot 中的 Locale。

英文文档：

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.

public void setLocale(java.util.Locale locale)

设置将在解析或格式化日期和时间时使用的 Locale。如果设置为 null，则将使用存储在当前请求的 javax.faces.component.UIViewRoot 中的 Locale。

locale

新的 Locale（或者 null）。

英文文档：

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)

public String getPattern()

返回将在格式化和解析日期和时间时使用的格式模式。

英文文档：

getPattern

public String getPattern()

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

public void setPattern(String pattern)

设置将在格式化和解析日期和时间时使用的格式模式。有效值是 java.text.SimpleDateFormat 支持的那些值。当调用 getAsObject() 或 getAsString() 时，无效值将导致 ConverterException。

pattern

新的格式模式

英文文档：

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

public String getTimeStyle()

返回将用于格式化或解析时间的样式。如果未设置，则返回默认值 default。

英文文档：

getTimeStyle

public 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(String timeStyle)

设置将用于格式化或解析时间的样式。有效值有 default、short、medium、long 和 full。当调用 getAsObject() 或 getAsString() 时，无效值将导致 ConverterException。

timeStyle

新样式代码

英文文档：

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

public java.util.TimeZone getTimeZone()

返回用来解释时间值的 TimeZone。如果没有明确设置，则返回默认时区 GMT。

英文文档：

getTimeZone

public TimeZone getTimeZone()

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

public void setTimeZone(java.util.TimeZone timeZone)

设置用来解释时间值的 TimeZone。

timeZone

新时区

英文文档：

setTimeZone

public void setTimeZone(TimeZone timeZone)

Set the TimeZone used to interpret a time value.

Parameters:

timeZone - The new time zone

public String getType()

返回要格式化或解析的值的类型。如果没有明确设置，则返回默认类型 date。

英文文档：

getType

public 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(String type)

设置要格式化或解析的值的类型。有效值为 both、date 或 time。当调用 getAsObject() 或 getAsString() 时，无效值将导致 ConverterException。

type

新日期样式

英文文档：

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

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

Throws	ConverterException: NullPointerException 如果无法成功执行转换
Throws	NullPointerException: NullPointerException 如果 context 或 component 为 null

英文文档：

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

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

Throws	ConverterException: NullPointerException 如果无法成功执行转换
Throws	NullPointerException: NullPointerException 如果 context 或 component 为 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

public Object saveState(FacesContext context)

英文文档：

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

public void restoreState(FacesContext context,
                         Object state)

public boolean isTransient()

public void setTransient(boolean transientFlag)