NumberConverter (Java EE 5)

java.lang.Number 值的 Converter 实现。

getAsObject() 方法根据以下算法将 String 解析为 java.lang.Double 或 java.lang.Long：

• 如果指定的 String 为 null，则返回 null。否则，在继续执行前去除前导空格和尾部的空格。
• 如果指定的 String（去除空格后）长度为 0，则返回 null。
• 如果 locale 属性不为 null，则使用该 Locale 管理解析。否则，使用 UIViewRoot 的 Locale。
• 如果指定了 pattern，则其语法必须遵守 java.text.DecimalFormat 指定的规则。此类模式将用于解析，并且将忽略 type 属性。
• 如果尚未指定 pattern，则将根据 type 属性进行解析，它应该为货币、数字或百分比。通过调用 java.text.NumberFormat 类的 getCurrencyInstance()、getNumberInstance() 或 getPercentInstance() 方法，并传入选择的 Locale，可以分别确定货币、数字和百分比的解析模式。
• 如果 integerOnly 属性设置为 true，则将仅解析 String 的整数部分。有关详细信息，请参见 java.text.NumberFormat 类的 setParseIntegerOnly() 方法的 JavaDoc。

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

• 如果指定的值为 null，则返回长度为 0 的 String。
• 如果指定的值为 String，则不加修改地返回该值。
• 如果 locale 属性不为 null，则使用该 Locale 管理格式化。否则，使用 FacesContext 中的 Locale。
• 如果指定了 pattern，则其语法必须遵守 java.text.DecimalFormat 指定的规则。此类模式将用于格式化，并且将忽略 type 属性（以及在下一段中描述的有关格式化的选项）。
• 如果尚未指定 pattern，则将根据 type 属性进行格式化，它将该值格式化为货币、数字或百分比。通过调用 java.text.NumberFormat 类的 getCurrencyInstance()、getNumberInstance() 或 getPercentInstance() 方法，并传入选择的 Locale，可以分别确定货币、数字和百分比的格式模式。此外，将对该格式模式应用以下属性（如果指定）：
  • 如果 groupingUsed 属性为 true，则对相应的 NumberFormat 实例调用 setGroupingUsed(true) 方法。
  • 将根据为 maxFractionDigits、maxIntegerDigits、minFractionDigits 和 minIntegerDigits 属性设置的任何值来配置结果整数部分和小数部分的最小位数和最大位数。
  • 如果类型设置为 currency，也可以使用 currencyCode 或 currencySymbol 属性配置要使用的货币符号。如果设置了两者，则 currencyCode 的值优先于 JDK 1.4（或更高版本）JVM；否则 currencySymbol 的值优先。

Converter implementation for java.lang.Number values.

The getAsObject() method parses a String into an java.lang.Double or java.lang.Long, 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.DecimalFormat. Such a pattern will be used to parse, and the type property will be ignored.
• If a pattern has not been specified, parsing will be based on the type property, which expects a currency, a number, or a percent. The parse pattern for currencies, numbers, and percentages is determined by calling the getCurrencyInstance(), getNumberInstance(), or getPercentInstance() method of the java.text.NumberFormat class, passing in the selected Locale.
• If the integerOnly property has been set to true, only the integer portion of the String will be parsed. See the JavaDocs for the setParseIntegerOnly() method of the java.text.NumberFormat class for more information.

The getAsString() method expects a value of type java.lang.Number (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 FacesContext.
• If a pattern has been specified, its syntax must conform the rules specified by java.text.DecimalFormat. Such a pattern will be used to format, and the type property (along with related formatting options described in the next paragraph) will be ignored.
• If a pattern has not been specified, formatting will be based on the type property, which formats the value as a currency, a number, or a percent. The format pattern for currencies, numbers, and percentages is determined by calling the percentages is determined by calling the getCurrencyInstance(), getNumberInstance(), or getPercentInstance() method of the java.text.NumberFormat class, passing in the selected Locale. In addition, the following properties will be applied to the format pattern, if specified:
  • If the groupingUsed property is true, the setGroupingUsed(true) method on the corresponding NumberFormat instance will be called.
  • The minimum and maximum number of digits in the integer and fractional portions of the result will be configured based on any values set for the maxFractionDigits, maxIntegerDigits, minFractionDigits, and minIntegerDigits properties.
  • If the type is set to currency, it is also possible to configure the currency symbol to be used, using either the currencyCode or currencySymbol properties. If both are set, the value for currencyCode takes precedence on a JDK 1.4 (or later) JVM; otherwise, the value for currencySymbol takes precedence.

英文文档：

CONVERTER_ID

public static final String CONVERTER_ID

The standard converter id for this converter.

See Also:

Constant Field Values

英文文档：

CURRENCY_ID

public static final String CURRENCY_ID

The message identifier of the FacesMessage to be created if the conversion to Number 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

英文文档：

NUMBER_ID

public static final String NUMBER_ID

The message identifier of the FacesMessage to be created if the conversion to Number 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

英文文档：

PATTERN_ID

public static final String PATTERN_ID

The message identifier of the FacesMessage to be created if the conversion to Number 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

英文文档：

PERCENT_ID

public static final String PERCENT_ID

The message identifier of the FacesMessage to be created if the conversion to Number 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 Number 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 NumberConverter()

英文文档：

NumberConverter

public NumberConverter()

public String getCurrencyCode()

返回 type 为 currency 的 getAsString() 所使用的 ISO 4217 货币代码。如果未设置，则使用的值将根据格式 Locale 确定。

英文文档：

getCurrencyCode

public String getCurrencyCode()

Return the ISO 4217 currency code used by getAsString() with a type of currency. If not set, the value used will be based on the formatting Locale.

public void setCurrencyCode(String currencyCode)

设置 type 为 currency 的 getAsString() 所使用的 ISO 4217 货币代码。

currencyCode

新货币代码

英文文档：

setCurrencyCode

public void setCurrencyCode(String currencyCode)

Set the ISO 4217 currency code used by getAsString() with a type of currency.

Parameters:

currencyCode - The new currency code

public String getCurrencySymbol()

返回 type 为 currency 的 getAsString() 所使用的货币符号。如果未设置，则使用的值将根据格式 Locale 确定。

英文文档：

getCurrencySymbol

public String getCurrencySymbol()

Return the currency symbol used by getAsString() with a type of currency. If not set, the value used will be based on the formatting Locale.

public void setCurrencySymbol(String currencySymbol)

设置 type 为 currency 的 getAsString() 所使用的货币符号。

currencySymbol

新货币符号

英文文档：

setCurrencySymbol

public void setCurrencySymbol(String currencySymbol)

Set the currency symbol used by getAsString() with a type of currency.

Parameters:

currencySymbol - The new currency symbol

public boolean isGroupingUsed()

如果 getAsString 应该包含分组分隔符（如有必要），则返回 true。如果未修改，则默认值为 true。

英文文档：

isGroupingUsed

public boolean isGroupingUsed()

Return true if getAsString should include grouping separators if necessary. If not modified, the default value is true.

public void setGroupingUsed(boolean groupingUsed)

设置指示 getAsString() 是否应该包含分组分隔符（如有必要）的标志。

groupingUsed

新的分组使用的标志

英文文档：

setGroupingUsed

public void setGroupingUsed(boolean groupingUsed)

Set the flag indicating whether getAsString() should include grouping separators if necessary.

Parameters:

groupingUsed - The new grouping used flag

public boolean isIntegerOnly()

仅当给定值的整数部分应该从 getAsObject() 返回时，返回 true。如果未修改，则默认值为 false。

英文文档：

isIntegerOnly

public boolean isIntegerOnly()

Return true if only the integer portion of the given value should be returned from getAsObject(). If not modified, the default value is false.

public void setIntegerOnly(boolean integerOnly)

仅当给定值的整数部分应该从 getAsObject() 返回时，设置为 true。

integerOnly

新的 integer-only 标志

英文文档：

setIntegerOnly

public void setIntegerOnly(boolean integerOnly)

Set to true if only the integer portion of the given value should be returned from getAsObject().

Parameters:

integerOnly - The new integer-only flag

public int getMaxFractionDigits()

返回 getAsString() 应该在结果中呈现的小数部分的最大位数。

英文文档：

getMaxFractionDigits

public int getMaxFractionDigits()

Return the maximum number of digits getAsString() should render in the fraction portion of the result.

public void setMaxFractionDigits(int maxFractionDigits)

设置 getAsString() 应该在结果中呈现的小数部分的最大位数。如果未设置，则数值将取决于要转换的值。

maxFractionDigits

新的限制

英文文档：

setMaxFractionDigits

public void setMaxFractionDigits(int maxFractionDigits)

Set the maximum number of digits getAsString() should render in the fraction portion of the result. If not set, the number of digits depends on the value being converted.

Parameters:

maxFractionDigits - The new limit

public int getMaxIntegerDigits()

返回 getAsString() 应该在结果中呈现的整数部分的最大位数。

英文文档：

getMaxIntegerDigits

public int getMaxIntegerDigits()

Return the maximum number of digits getAsString() should render in the integer portion of the result.

public void setMaxIntegerDigits(int maxIntegerDigits)

设置 getAsString() 应该在结果中呈现的整数部分的最大位数。如果未设置，则数值将取决于要转换的值。

maxIntegerDigits

新的限制

英文文档：

setMaxIntegerDigits

public void setMaxIntegerDigits(int maxIntegerDigits)

Set the maximum number of digits getAsString() should render in the integer portion of the result. If not set, the number of digits depends on the value being converted.

Parameters:

maxIntegerDigits - The new limit

public int getMinFractionDigits()

返回 getAsString() 应该在结果中呈现的小数部分的最小位数。

英文文档：

getMinFractionDigits

public int getMinFractionDigits()

Return the minimum number of digits getAsString() should render in the fraction portion of the result.

public void setMinFractionDigits(int minFractionDigits)

设置 getAsString() 应该在结果中呈现的小数部分的最小位数。如果未设置，则数值将取决于要转换的值。

minFractionDigits

新的限制

英文文档：

setMinFractionDigits

public void setMinFractionDigits(int minFractionDigits)

Set the minimum number of digits getAsString() should render in the fraction portion of the result. If not set, the number of digits depends on the value being converted.

Parameters:

minFractionDigits - The new limit

public int getMinIntegerDigits()

返回 getAsString() 应该在结果中呈现的整数部分的最小位数。

英文文档：

getMinIntegerDigits

public int getMinIntegerDigits()

Return the minimum number of digits getAsString() should render in the integer portion of the result.

public void setMinIntegerDigits(int minIntegerDigits)

设置 getAsString() 应该在结果中呈现的整数部分的最小位数。如果未设置，则数值将取决于要转换的值。

minIntegerDigits

新的限制

英文文档：

setMinIntegerDigits

public void setMinIntegerDigits(int minIntegerDigits)

Set the minimum number of digits getAsString() should render in the integer portion of the result. If not set, the number of digits depends on the value being converted.

Parameters:

minIntegerDigits - The new limit

public java.util.Locale getLocale()

返回解析数字时使用的 Locale。如果此值为 null，则将使用存储在当前请求的 javax.faces.component.UIViewRoot 中的 Locale。

英文文档：

getLocale

public Locale getLocale()

Return the Locale to be used when parsing numbers. If this value is null, the Locale stored in the UIViewRoot for the current request will be utilized.

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

public void setPattern(String pattern)

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

pattern

新的格式模式

英文文档：

setPattern

public void setPattern(String pattern)

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

Parameters:

pattern - The new format pattern

public String getType()

返回将在格式化和解析数字时使用的数字类型。如果未修改，则默认类型为 number。

英文文档：

getType

public String getType()

Return the number type to be used when formatting and parsing numbers. If not modified, the default type is number.

public void setType(String type)

设置将在格式化和解析数字时使用的数字类型。有效值有 currency、number 或 percent。当调用 getAsObject() 或 getAsString() 时，无效值将导致 ConverterException。

type

新的数字样式

英文文档：

setType

public void setType(String type)

Set the number type to be used when formatting and parsing numbers. Valid values are currency, number, or percent. An invalid value will cause a ConverterException when getAsObject() or getAsString() is called.

Parameters:

type - The new number 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)