Converter (Java EE 5)

Converter 是一个接口，它描述可以在模型数据对象及其适合于呈现的 String 表示形式之间执行 Object-to-String 和 String-to-Object 转换的 Java 类。

Converter 实现必须拥有一个公共的无参数构造方法。此外，如果 Converter 类希望保存配置属性值并用组件树恢复，则该实现还必须实现 StateHolder。

从 1.2 版本的规范开始，上述无参数构造方法要求引入了一种例外情况。如果转换器具有一个用 Class 实例作为参数的单参数构造方法，并且要转换数据的 Class 在转换器实例化时已知，则必须使用此构造方法来实例化转换器，而不是使用无参数的构造方法。这样便可对 Java 枚举类型进行按类转换。

如果某个 Converter 实现需要 java.util.Locale 实现其功能，则它必须包含取自当前 FacesContext 的 javax.faces.component.UIViewRoot 的 Locale，除非 Converter 保留其自己的 Locale 作为其状态的一部分。

Converter is an interface describing a Java class that can perform Object-to-String and String-to-Object conversions between model data objects and a String representation of those objects that is suitable for rendering.

Converter implementations must have a zero-arguments public constructor. In addition, if the Converter class wishes to have configuration property values saved and restored with the component tree, the implementation must also implement StateHolder.

Starting with version 1.2 of the specification, an exception to the above zero-arguments constructor requirement has been introduced. If a converter has a single argument constructor that takes a Class instance and the Class of the data to be converted is known at converter instantiation time, this constructor must be used to instantiate the converter instead of the zero-argument version. This enables the per-class conversion of Java enumerated types.

If any Converter implementation requires a java.util.Locale to perform its job, it must obtain that Locale from the UIViewRoot of the current FacesContext, unless the Converter maintains its own Locale as part of its state.

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

将指定的字符串值（与指定的 UIComponent 关联）转换为适合于在请求处理生命周期的应用请求值 阶段存储的模型数据对象。

context	要处理的请求的 FacesContext
component	与此模型对象值关联的 UIComponent
value	要转换的 String 值（可以为 null）
return	如果要转换的值为 null，则返回 null；否则返回转换的结果
Throws	ConverterException: 如果无法成功执行转换
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

getAsObject

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.

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)

将指定的模型对象值（与指定的 UIComponent 关联）转换为适合包含于请求处理生命周期的呈现响应 阶段所生成的响应的字符串。

context	要处理的请求的 FacesContext
component	与此模型对象值关联的 UIComponent
value	要转换的模型对象值（可以为 null）
return	如果值为 null，则返回长度为 0 String；否则返回转换的结果
Throws	ConverterException: 如果无法成功执行转换
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

getAsString

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.

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

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.