RenderKit (Java EE 5)

RenderKit 表示 Renderer 实例的 Collection，这些实例了解如何为特定客户端呈现 JavaServer Faces UIComponent 实例。通常，RenderKit 专门用来处理一些客户端设备类型、标记语言和/或用户 Locale 的组合。RenderKit 还用作关联 Renderer 实例的 Factory，这些实例执行每个组件实际的呈现过程。

典型的 JavaServer Faces 实现将在 Web 应用程序启动时配置一个或多个 RenderKit 实例。通过调用 RenderKitFactory 的 getRenderKit() 方法可以获得这些实例。因为 RenderKit 实例是共享的，所以它们必须以线程安全的方式实现。当前规范限制同一应用程序中存在多个起作用的 RenderKit 实例，因此需要一个了解如何处理这种情况的自定义 javax.faces.application.ViewHandler 实例。在规范的将来版本中，将取消此限制。

RenderKit 实例还必须提供一个 ResponseStateManager 实例，它在保存和恢复树结构和状态的过程中使用。

RenderKit represents a collection of Renderer instances that, together, know how to render JavaServer Faces UIComponent instances for a specific client. Typically, RenderKits are specialized for some combination of client device type, markup language, and/or user Locale. A RenderKit also acts as a Factory for associated Renderer instances, which perform the actual rendering process for each component.

A typical JavaServer Faces implementation will configure one or more RenderKit instances at web application startup. They are made available through calls to the getRenderKit() methods of RenderKitFactory. Because RenderKit instances are shared, they must be implemented in a thread-safe manner. Due to limitations in the current specification having multiple RenderKit instances at play in the same application requires a custom ViewHandler instance that is aware of how to deal with this case. This limitation will be lifted in a future version of the spec.

The RenderKit instance must also vend a ResponseStateManager instance, which is used in the process of saving and restoring tree structure and state.

public RenderKit()

英文文档：

RenderKit

public RenderKit()

abstract public void addRenderer(String family, String rendererType, Renderer renderer)

将与指定组件 family 和 rendererType 关联的指定 Renderer 实例注册已向此 RenderKit 注册的 Renderer 集，将之前注册的任何 Renderer 替换成此标识符的组合。

family	要注册的 Renderer 组件系列
rendererType	要注册的 Renderer 的 Renderer 类型
renderer	要注册的 Renderer 实例
Throws	NullPointerException: 如果 family、rendererType 或 renderer 为 null

英文文档：

addRenderer

public abstract void addRenderer(String family,
                                 String rendererType,
                                 Renderer renderer)

Register the specified Renderer instance, associated with the specified component family and rendererType, to the set of Renderers registered with this RenderKit, replacing any previously registered Renderer for this combination of identifiers.

Parameters:

family - Component family of the Renderer to register

rendererType - Renderer type of the Renderer to register

renderer - Renderer instance we are registering

Throws:

NullPointerException - if family or rendererType or renderer is null

abstract public Renderer getRenderer(String family, String rendererType)

返回为指定组件 family 和 rendererType 最新注册的 Renderer 实例（如果有）；否则返回 null。

family	请求的 Renderer 实例的组件系列
rendererType	请求的 Renderer 实例的 Renderer 类型
Throws	NullPointerException: 如果 family 或 rendererType 为 null

英文文档：

getRenderer

public abstract Renderer getRenderer(String family,
                                     String rendererType)

Return the Renderer instance most recently registered for the specified component family and rendererType, if any; otherwise, return null.

Parameters:

family - Component family of the requested Renderer instance

rendererType - Renderer type of the requested Renderer instance

Throws:

NullPointerException - if family or rendererType is null

abstract public ResponseStateManager getResponseStateManager()

返回 ResponseStateManager 实例，以处理呈现技术特有的状态管理决策。

英文文档：

getResponseStateManager

public abstract ResponseStateManager getResponseStateManager()

Return an instance of ResponseStateManager to handle rendering technology specific state management decisions.

abstract public ResponseWriter createResponseWriter(java.io.Writer writer, String contentTypeList, String characterEncoding)

使用提供的 Writer 创建具有指定（可选）内容类型和字符编码的新 ResponseWriter 实例。

建议实现者参考类 javax.servlet.ServletResponse 的 getCharacterEncoding() 方法，以获取此方法所需的 characterEncoding 值。我们已经获得了此响应的 Writer（因为它最终将传递给此方法），所以我们知道在呈现响应期间不能更改字符编码。

writer	必须据以构建此 ResponseWriter 的 writer。
contentTypeList	此响应的内容类型的“Accept 头样式 (Accept header style)”列表；如果 RenderKit 应该选择最适合的类型，则为 null。从当前版本起，此参数的标准 RenderKit 接受的值包括任何有效的“Accept 头样式”String，包括 String text/html、application/xhtml+xml、application/xml 或 text/xml。这在将来的版本中可能会发生变化。RenderKit 必须支持此参数使用直接来自 Accept HTTP 头的值，因此需要根据 Accept 头的规范进行解析。有关 Accept 头规范，请参见 RFC 2616 的第 14.1 节。
characterEncoding	如“ISO-8859-1”（对于此 ResponseWriter）；如果 RenderKit 应该选择最合适的编码，则为 null。有关字符编码的列表，请参见 the IANA。
return	新的 ResponseWriter。
Throws	IllegalArgumentException: 如果 contentTypeList 中找不到匹配的内容类型，或者使用与实现有关的最适应算法找不到合适的内容类型，或者对于参数 characterEncoding 找不到匹配的字符编码。

英文文档：

createResponseWriter

public abstract ResponseWriter createResponseWriter(Writer writer,
                                                    String contentTypeList,
                                                    String characterEncoding)

Use the provided Writer to create a new ResponseWriter instance for the specified (optional) content type, and character encoding.

Implementors are advised to consult the getCharacterEncoding() method of class ServletResponse to get the required value for the characterEncoding for this method. Since the Writer for this response will already have been obtained (due to it ultimately being passed to this method), we know that the character encoding cannot change during the rendering of the response.

Parameters:

writer - the Writer around which this ResponseWriter must be built.

contentTypeList - an "Accept header style" list of content types for this response, or null if the RenderKit should choose the best fit. As of the current version, the values accepted by the Standard render-kit for this parameter include any valid "Accept header style" String that includes the String text/html, application/xhtml+xml, application/xml or text/xml. This may change in a future version. The RenderKit must support a value for this argument that comes straight from the Accept HTTP header, and therefore requires parsing according to the specification of the Accept header. Please see Section 14.1 of RFC 2616 for the specification of the Accept header.

characterEncoding - such as "ISO-8859-1" for this ResponseWriter, or null if the RenderKit should choose the best fit. Please see the IANA for a list of character encodings.

Returns:

a new ResponseWriter.

Throws:

IllegalArgumentException - if no matching content type can be found in contentTypeList, no appropriate content type can be found with the implementation dependent best fit algorithm, or no matching character encoding can be found for the argument characterEncoding.

abstract public ResponseStream createResponseStream(java.io.OutputStream out)

使用提供的 OutputStream 创建新的 ResponseStream 实例。

英文文档：

createResponseStream

public abstract ResponseStream createResponseStream(OutputStream out)

Use the provided OutputStream to create a new ResponseStream instance.

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