ViewHandler (Java EE 5)

ViewHandler 提供一种可插入机制，允许使用 JavaServer Faces 规范的实现或应用程序提供它们自己对请求处理生命周期的呈现响应 和恢复视图 阶段活动的处理。这使实现可以支持不同的响应生成技术，以及保存和恢复每个视图状态的备用策略。

有关 ViewHandler 如何与 StateManager 交互的信息，请参见 StateManager。

ViewHandler is the pluggablity mechanism for allowing implementations of or applications using the JavaServer Faces specification to provide their own handling of the activities in the Render Response and Restore View phases of the request processing lifecycle. This allows for implementations to support different response generation technologies, as well as alternative strategies for saving and restoring the state of each view.

Please see StateManager for information on how the ViewHandler interacts the StateManager.

英文文档：

CHARACTER_ENCODING_KEY

public static final String CHARACTER_ENCODING_KEY

The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.

See Also:

Constant Field Values

英文文档：

DEFAULT_SUFFIX_PARAM_NAME

public static final String DEFAULT_SUFFIX_PARAM_NAME

Allow the web application to define an alternate suffix for pages containing JSF content. If this init parameter is not specified, the default value is taken from the value of the constant DEFAULT_SUFFIX.

See Also:

Constant Field Values

英文文档：

DEFAULT_SUFFIX

public static final String DEFAULT_SUFFIX

The value to use for the default extension if the webapp is using url extension mapping.

See Also:

Constant Field Values

public ViewHandler()

英文文档：

ViewHandler

public ViewHandler()

abstract public java.util.Locale calculateLocale(FacesContext context)

返回用于当前客户端该请求和后续请求的相应 Locale。

context	当前请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

calculateLocale

public abstract Locale calculateLocale(FacesContext context)

Returns an appropriate Locale to use for this and subsequent requests for the current client.

Parameters:

context - FacesContext for the current request

Throws:

NullPointerException - if context is null

public String calculateCharacterEncoding(FacesContext context)

返回用于此请求的正确字符编码。

使用以下算法。

• 检查 Content-Type 请求头。如果它有 charset 参数，则将其提取并作为编码返回。

• 如果未找到 charset 参数，则通过调用 getSession(boolean) 同时将 false 作为参数传递来检查会话是否存在。如果该方法返回 true，则通过调用 ExternalContext#getSessionMap 获取会话 Map，并查找符号常量 ViewHandler#CHARACTER_ENCODING_KEY 的值给定的该键下的值。如果存在，则返回该值（该值已转换为 String）。

• 否则，返回 null。

英文文档：

calculateCharacterEncoding

public String calculateCharacterEncoding(FacesContext context)

Returns the correct character encoding to be used for this request.

The following algorithm is employed.

• Examine the Content-Type request header. If it has a charset parameter, extract it and return that as the encoding.

• If no charset parameter was found, check for the existence of a session by calling ExternalContext.getSession(boolean) passing false as the argument. If that method returns true, get the session Map by calling ExternalContext.getSessionMap() and look for a value under the key given by the value of the symbolic constant CHARACTER_ENCODING_KEY. If present, return the value, converted to String.

• Otherwise, return null

abstract public String calculateRenderKitId(FacesContext context)

返回当前客户端的该请求和后续请求的相应 renderKitId。此方法返回 null 是错误的。

默认返回值为 javax.faces.render.RenderKitFactory#HTML_BASIC_RENDER_KIT。

context	当前请求的 FacesContext
Throws	NullPointerException: 如果 context 为 null

英文文档：

calculateRenderKitId

public abstract String calculateRenderKitId(FacesContext context)

Return an appropriate renderKitId for this and subsequent requests from the current client. It is an error for this method to return null.

The default return value is RenderKitFactory.HTML_BASIC_RENDER_KIT.

Parameters:

context - FacesContext for the current request

Throws:

NullPointerException - if context is null

abstract public UIViewRoot createView(FacesContext context, String viewId)

创建并返回使用参数 FacesContext 和 viewId 中的信息初始化的新 UIViewRoot 实例。

如果该 FacesContext 中存在现有的 ViewRoot，则此方法必须将其 locale 和 renderKitId 复制到此新视图根。如果不存在，则此方法必须调用 #calculateLocale 和 #calculateRenderKitId，并将结果分别存储为新建的 UIViewRoot 的 locale 和 renderKitId 属性的值。

Throws

NullPointerException: 如果 context 为 null

英文文档：

createView

public abstract UIViewRoot createView(FacesContext context,
                                      String viewId)

Create and return a new UIViewRoot instance initialized with information from the argument FacesContext and viewId.

If there is an existing ViewRoot available on the FacesContext, this method must copy its locale and renderKitId to this new view root. If not, this method must call calculateLocale(javax.faces.context.FacesContext) and calculateRenderKitId(javax.faces.context.FacesContext), and store the results as the values of the locale and renderKitId, proeprties, respectively, of the newly created UIViewRoot.

Throws:

NullPointerException - if context is null

abstract public String getActionURL(FacesContext context, String viewId)

返回选择指定视图标识符且适于呈现的 URL（ExternalContext 的 encodeActionURL() 方法执行可选编码后）。

context	此请求的 FacesContext
viewId	所需视图的视图标识符
Throws	IllegalArgumentException: 如果 viewId 对此 ViewHandler 无效。
Throws	NullPointerException: 如果 context 或 viewId 为 null。

英文文档：

getActionURL

public abstract String getActionURL(FacesContext context,
                                    String viewId)

Return a URL suitable for rendering (after optional encoding performed by the encodeActionURL() method of ExternalContext) that selects the specified view identifier.

Parameters:

context - FacesContext for this request

viewId - View identifier of the desired view

Throws:

IllegalArgumentException - if viewId is not valid for this ViewHandler.

NullPointerException - if context or viewId is null.

abstract public String getResourceURL(FacesContext context, String path)

返回选择指定 Web 应用程序资源且适于呈现的 URL（ExternalContext 的 encodeResourceURL() 方法执行可选编码后）。如果指定的路径以斜杠开头，则必须将其视作上下文相关；否则，必须将其视作与当前视图的操作 URL 相关。

context	当前请求的 FacesContext
path	要转换为 URL 的资源路径
Throws	IllegalArgumentException: 如果 viewId 对此 ViewHandler 无效。
Throws	NullPointerException: 如果 context 或 path 为 null。

英文文档：

getResourceURL

public abstract String getResourceURL(FacesContext context,
                                      String path)

Return a URL suitable for rendering (after optional encoding perfomed by the encodeResourceURL() method of ExternalContext) that selects the specifed web application resource. If the specified path starts with a slash, it must be treated as context relative; otherwise, it must be treated as relative to the action URL of the current view.

Parameters:

context - FacesContext for the current request

path - Resource path to convert to a URL

Throws:

IllegalArgumentException - if viewId is not valid for this ViewHandler.

NullPointerException - if context or path is null.

public void initView(FacesContext context) throws FacesException

初始化请求处理生命周期的视图。

此方法必须在请求处理生命周期的恢复视图阶段 的开始调用。它负责执行任何对生命周期操作必要的每个请求的初始化。

默认实现调用 #calculateCharacterEncoding 并将结果（如果为非 null）传入 ExternalContext#setRequestCharacterEncoding 方法。

Throws

FacesException: 如果设置编码时发生问题，例如编码不受支持时，底层 Servlet 或 Portlet 技术抛出的 UnsupportedEncodingException。

英文文档：

initView

public void initView(FacesContext context)
              throws FacesException

Initialize the view for the request processing lifecycle.

This method must be called at the beginning of the Restore View Phase of the Request Processing Lifecycle. It is responsible for performing any per-request initialization necessary to the operation of the lifycecle.

The default implementation calls calculateCharacterEncoding(javax.faces.context.FacesContext) and passes the result, if non-null into the ExternalContext.setRequestCharacterEncoding(java.lang.String) method.

Throws:

FacesException - if a problem occurs setting the encoding, such as the UnsupportedEncodingException thrown by the underlying Servlet or Portlet technology when the encoding is not supported.

abstract public void renderView(FacesContext context, UIViewRoot viewToRender) throws java.io.IOException, FacesException

执行所需的任何操作以将响应视图呈现给与当前 FacesContext 关联的响应对象。

context	当前请求的 FacesContext
viewToRender	要呈现的视图
Throws	java.io.IOException: 如果发生输入/输出错误
Throws	NullPointerException: 如果 context 或 viewToRender 为 null
Throws	FacesException: 如果发生 servlet 错误

英文文档：

renderView

public abstract void renderView(FacesContext context,
                                UIViewRoot viewToRender)
                         throws IOException,
                                FacesException

Perform whatever actions are required to render the response view to the response object associated with the current FacesContext.

Parameters:

context - FacesContext for the current request

viewToRender - the view to render

Throws:

IOException - if an input/output error occurs

NullPointerException - if context or viewToRender is null

FacesException - if a servlet error occurs

abstract public UIViewRoot restoreView(FacesContext context, String viewId)

执行所需的任何操作以恢复与指定 FacesContext 和 viewId 关联的视图。可以委托给关联的 StateManager 的 restoreView 来执行恢复视图的实际工作。如果没有可用的指定 viewId 的状态，则返回 null。

context	当前请求的 FacesContext
viewId	当前请求的视图标识符
Throws	NullPointerException: 如果 context 为 null
Throws	FacesException: 如果发生 servlet 错误

英文文档：

restoreView

public abstract UIViewRoot restoreView(FacesContext context,
                                       String viewId)

Perform whatever actions are required to restore the view associated with the specified FacesContext and viewId. It may delegate to the restoreView of the associated StateManager to do the actual work of restoring the view. If there is no available state for the specified viewId, return null.

Parameters:

context - FacesContext for the current request

viewId - the view identifier for the current request

Throws:

NullPointerException - if context is null

FacesException - if a servlet error occurs

abstract public void writeState(FacesContext context) throws java.io.IOException

采取任何适当的操作立即写出当前的状态信息（通过调用 StateManager#writeState），或注明稍后应写出状态信息的位置。

context	当前请求的 FacesContext
Throws	java.io.IOException: 如果发生输入/输出错误
Throws	NullPointerException: 如果 context 为 null

英文文档：

writeState

public abstract void writeState(FacesContext context)
                         throws IOException

Take any appropriate action to either immediately write out the current state information (by calling StateManager.writeState(javax.faces.context.FacesContext, java.lang.Object), or noting where state information should later be written.

Parameters:

context - FacesContext for the current request

Throws:

IOException - if an input/output error occurs

NullPointerException - if context is null

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