Renderer (Java EE 5)

Renderer 将 UIComponent 的内部表示形式转换为与正在为特定请求创建的响应关联的输出流（或 writer）。每个 Renderer 都了解如何呈现一种或多种 UIComponent 类型（或类），并且为每个支持的 UIComponent 公布一组与呈现有关的属性。

Renderer 系列被打包成 RenderKit，共同支持呈现与 FacesContext 关联的视图中的所有 UIComponent。在特定 RenderKit 的 Renderer 集内，每个 Renderer 都使用 rendererType 属性唯一地标识。

各个 Renderer 实例将在呈现过程中根据需要实例化，并在 Web 应用程序的剩余生命周期内一直存在。因为每个实例都有可能从一个以上的请求处理线程中同时调用，所以必须以线程安全的方式为其编程。

A Renderer converts the internal representation of UIComponents into the output stream (or writer) associated with the response we are creating for a particular request. Each Renderer knows how to render one or more UIComponent types (or classes), and advertises a set of render-dependent attributes that it recognizes for each supported UIComponent.

Families of Renderers are packaged as a RenderKit, and together support the rendering of all of the UIComponents in a view associated with a FacesContext. Within the set of Renderers for a particular RenderKit, each must be uniquely identified by the rendererType property.

Individual Renderer instances will be instantiated as requested during the rendering process, and will remain in existence for the remainder of the lifetime of a web application. Because each instance may be invoked from more than one request processing thread simultaneously, they MUST be programmed in a thread-safe manner.

public Renderer()

英文文档：

Renderer

public Renderer()

public void decode(FacesContext context, UIComponent component)

从指定 FacesContext 中包含的请求中解码指定 UIComponent 的任何新状态，并将此状态存储在 UIComponent 中。

在解码期间，通过对关联的 UIComponent 调用 queueEvent()，可以将事件加入队列，以便稍后处理（由注册的事件侦听器实现）。

context	要处理的请求的 FacesContext
component	要解码的 UIComponent。
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

decode

public void decode(FacesContext context,
                   UIComponent component)

Decode any new state of the specified UIComponent from the request contained in the specified FacesContext, and store that state on the UIComponent.

During decoding, events may be enqueued for later processing (by event listeners that have registered an interest), by calling queueEvent() on the associated UIComponent.

Parameters:

context - FacesContext for the request we are processing

component - UIComponent to be decoded.

Throws:

NullPointerException - if context or component is null

public void encodeBegin(FacesContext context, UIComponent component) throws java.io.IOException

将一开始指定的 UIComponent 呈现给与正在创建的响应关联的输出流或 writer。如果上一次对此组件调用 getConvertedValue() 时转换尝试失败，则应使用 decode() 执行期间保存的状态信息来复制错误的输入。

context	要处理的请求的 FacesContext
component	要呈现的 UIComponent
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

encodeBegin

public void encodeBegin(FacesContext context,
                        UIComponent component)
                 throws IOException

Render the beginning specified UIComponent to the output stream or writer associated with the response we are creating. If the conversion attempted in a previous call to getConvertedValue() for this component failed, the state information saved during execution of decode() should be used to reproduce the incorrect input.

Parameters:

context - FacesContext for the request we are processing

component - UIComponent to be rendered

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context or component is null

public void encodeChildren(FacesContext context, UIComponent component) throws java.io.IOException

呈现此 UIComponent 的子组件，根据 encodeBegin() 描述的规则获取要呈现的相应值。仅当此组件的 rendersChildren 属性为 true 时，才调用此方法。

context	要创建的响应的 FacesContext
component	要呈现其子组件的 UIComponent
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

encodeChildren

public void encodeChildren(FacesContext context,
                           UIComponent component)
                    throws IOException

Render the child components of this UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered. This method will only be called if the rendersChildren property of this component is true.

Parameters:

context - FacesContext for the response we are creating

component - UIComponent whose children are to be rendered

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context or component is null

public void encodeEnd(FacesContext context, UIComponent component) throws java.io.IOException

呈现指定 UIComponent 当前状态的结束，根据 encodeBegin() 描述的规则获取要呈现的相应值。

context	要创建的响应的 FacesContext
component	要呈现的 UIComponent
Throws	java.io.IOException: 如果呈现期间发生输入/输出错误
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

encodeEnd

public void encodeEnd(FacesContext context,
                      UIComponent component)
               throws IOException

Render the ending of the current state of the specified UIComponent, following the rules described for encodeBegin() to acquire the appropriate value to be rendered.

Parameters:

context - FacesContext for the response we are creating

component - UIComponent to be rendered

Throws:

IOException - if an input/output error occurs while rendering

NullPointerException - if context or component is null

public String convertClientId(FacesContext context, String clientId)

将组件生成的客户端 ID 转换成适合向客户端传输的形式。

默认实现返回未更改的参数 clientId。

context	当前请求的 FacesContext
clientId	要转换成客户端特定格式的客户端标识符。
Throws	NullPointerException: 如果 context 或 clientId 为 null

英文文档：

convertClientId

public String convertClientId(FacesContext context,
                              String clientId)

Convert the component generated client id to a form suitable for transmission to the client.

The default implementation returns the argument clientId unchanged.

Parameters:

context - FacesContext for the current request

clientId - the client identifier to be converted to client a specific format.

Throws:

NullPointerException - if context or clientId is null

public boolean getRendersChildren()

返回一个标志，它指示此 Renderer 是否负责呈现请求呈现的组件的子组件。默认实现返回 false。

英文文档：

getRendersChildren

public boolean getRendersChildren()

Return a flag indicating whether this Renderer is responsible for rendering the children the component it is asked to render. The default implementation returns false.

public Object getConvertedValue(FacesContext context, UIComponent component, Object submittedValue) throws ConverterException

尝试将以前存储的状态信息转换成此组件需要的对象类型（如果有，则可以选择使用此组件的已注册 javax.faces.convert.Converter）。如果转换成功，则应该从此方法返回新的值；否则，应该抛出 ConverterException。

context	要处理的请求的 FacesContext
component	要解码的 UIComponent。
submittedValue	在 decode 期间存储在组件中的值。
Throws	ConverterException: 如果无法成功转换提交的值。
Throws	NullPointerException: 如果 context 或 component 为 null

英文文档：

getConvertedValue

public Object getConvertedValue(FacesContext context,
                                UIComponent component,
                                Object submittedValue)
                         throws ConverterException

Attempt to convert previously stored state information into an object of the type required for this component (optionally using the registered Converter for this component, if there is one). If conversion is successful, the new value should be returned from this method; if not, a ConverterException should be thrown.

Parameters:

context - FacesContext for the request we are processing

component - UIComponent to be decoded.

submittedValue - a value stored on the component during decode.

Throws:

ConverterException - if the submitted value cannot be converted successfully.

NullPointerException - if context or component is null

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