Renderer (Java EE 5)

Java EE API

previous page next page

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.faces.render Class Renderer

java.lang.Object
  javax.faces.render.Renderer

public abstract class Renderer
extends Object

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.

Constructor Summary
`Renderer()`

Method Summary
`String`	`convertClientId(FacesContext context, String clientId)` Convert the component generated client id to a form suitable for transmission to the client.
`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`.
`void`	`encodeBegin(FacesContext context, UIComponent component)` Render the beginning specified `UIComponent` to the output stream or writer associated with the response we are creating.
`void`	`encodeChildren(FacesContext context, UIComponent component)` Render the child components of this `UIComponent`, following the rules described for `encodeBegin()` to acquire the appropriate value to be rendered.
`void`	`encodeEnd(FacesContext context, UIComponent component)` 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.
`Object`	`getConvertedValue(FacesContext context, UIComponent component, Object submittedValue)` 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).
`boolean`	`getRendersChildren()` Return a flag indicating whether this `Renderer` is responsible for rendering the children the component it is asked to render.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

public Renderer()

英文文档：
Renderer

public Renderer()

Method Detail

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