Application (Java EE 5)

Application 表示每个 Web 应用程序单件对象，在这里基于 JavaServer Faces 的应用程序（或要提供扩展功能的实现）可以注册提供 JavaServer Faces 所需功能的应用程序级单件。在应用程序不选择自定义行为的情况下，提供每个对象的默认实现。

通过调用 ApplicationFactory 的 getApplication() 方法创建 Application 的实例。因为此实例是共享的，所以必须以线程安全的方式实现此实例。

该应用程序还作为在 Faces 配置文件中指定的若干个 Object 类型的工厂。请参见 Application#createComponent、Application#createConverter 和 Application#createValidator。

Application represents a per-web-application singleton object where applications based on JavaServer Faces (or implementations wishing to provide extended functionality) can register application-wide singletons that provide functionality required by JavaServer Faces. Default implementations of each object are provided for cases where the application does not choose to customize the behavior.

The instance of Application is created by calling the getApplication() method of ApplicationFactory. Because this instance is shared, it must be implemented in a thread-safe manner.

The application also acts as a factory for several types of Objects specified in the Faces Configuration file. Please see createComponent(java.lang.String), createConverter(java.lang.String), and createValidator(java.lang.String).

public Application()

英文文档：

Application

public Application()

abstract public ActionListener getActionListener()

返回要为此应用程序中所有 javax.faces.component.ActionSource 组件注册的默认 ActionListener。如果没有显式设置，则必须提供执行以下函数的默认实现 ：

• processAction() 方法必须首先调用 FacesContext.renderResponse()，以便在该方法返回后，绕过任何干扰生命周期阶段。
• processAction() 方法接着必须确定此事件的逻辑结果，如下所示：
  • 如果发起组件有非 null action 属性，则从属性中获取 MethodBinding 并对其调用 invoke()。将返回值（如果有）转换为 String，并将其用作逻辑结果。
  • 否则，逻辑结果为 null。
• processAction() 方法最后必须获取此应用程序的 NavigationHandler 实例并调用 NavigationHandler#handleNavigation ，同时传递：
  • 当前请求的 FacesContext
  • 如果此组件的 action 属性具有 MethodBinding 实例，则传递对其调用 MethodBinding#getExpressionString 的结果，否则传递 null
  • 上面确定的逻辑结果

注意，默认 ActionListener 的规范继续要求使用过时的属性 (action) 和类 (MethodBinding)。不幸的是，这是必需的，因为默认 ActionListener 必须继续与没有实现 javax.faces.component.ActionSource2 而仅实现了 javax.faces.component.ActionSource 的组件一起使用。

英文文档：

getActionListener

public abstract ActionListener getActionListener()

Return the default ActionListener to be registered for all ActionSource components in this appication. If not explicitly set, a default implementation must be provided that performs the following functions:

• The processAction() method must first call FacesContext.renderResponse() in order to bypass any intervening lifecycle phases, once the method returns.
• The processAction() method must next determine the logical outcome of this event, as follows:
  • If the originating component has a non-null action property, retrieve the MethodBinding from the property, and call invoke() on it. Convert the returned value (if any) to a String, and use it as the logical outcome.
  • Otherwise, the logical outcome is null.
• The processAction() method must finally retrieve the NavigationHandler instance for this application and call NavigationHandler.handleNavigation(javax.faces.context.FacesContext, java.lang.String, java.lang.String) passing:
  • the FacesContext for the current request
  • If there is a MethodBinding instance for the action property of this component, the result of calling MethodBinding.getExpressionString() on it, null otherwise
  • the logical outcome as determined above

Note that the specification for the default ActionListener contiues to call for the use of a deprecated property (action) and class (MethodBinding). Unfortunately, this is necessary because the default ActionListener must continue to work with components that do not implement ActionSource2, and only implement ActionSource.

abstract public void setActionListener(ActionListener listener)

设置要为所有 javax.faces.component.ActionSource 组件注册的默认 ActionListener。

setActionListener

public abstract void setActionListener(ActionListener listener)

Set the default ActionListener to be registered for all ActionSource components.

abstract public java.util.Locale getDefaultLocale()

返回此应用程序的默认 Locale。如果没有显式设置，则返回 null。

英文文档：

getDefaultLocale

public abstract Locale getDefaultLocale()

Return the default Locale for this application. If not explicitly set, null is returned.

abstract public void setDefaultLocale(java.util.Locale locale)

设置此应用程序的默认 Locale。

locale	新的默认 Locale
Throws	NullPointerException: 如果 locale 为 null

英文文档：

setDefaultLocale

public abstract void setDefaultLocale(Locale locale)

Set the default Locale for this application.

Parameters:

locale - The new default Locale

Throws:

NullPointerException - if locale is null

abstract public String getDefaultRenderKitId()

返回要用于呈现此应用程序的 renderKitId。如果没有显式设置，则返回 null。

英文文档：

getDefaultRenderKitId

public abstract String getDefaultRenderKitId()

Return the renderKitId to be used for rendering this application. If not explicitly set, null is returned.

abstract public void setDefaultRenderKitId(String renderKitId)

设置要用于呈现此应用程序的 renderKitId。除非客户端已提供支持在同一应用程序中使用多个 javax.faces.render.RenderKit 实例的自定义 ViewHandler，否则只能在应用程序启动时，在处理任何 Faces 请求之前，调用此方法。这是当前规范的局限性，可能在以后的版本中得到改进。

英文文档：

setDefaultRenderKitId

public abstract void setDefaultRenderKitId(String renderKitId)

Set the renderKitId to be used to render this application. Unless the client has provided a custom ViewHandler that supports the use of multiple RenderKit instances in the same application, this method must only be called at application startup, before any Faces requests have been processed. This is a limitation of the current Specification, and may be lifted in a future release.

abstract public String getMessageBundle()

返回要用于此应用程序的 JavaServer Faces 消息的 ResourceBundle 的完全限定类名。如果没有显式设置，则返回 null。

英文文档：

getMessageBundle

public abstract String getMessageBundle()

Return the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application. If not explicitly set, null is returned.

abstract public void setMessageBundle(String bundle)

设置要用于此应用程序的 JavaServer Faces 消息的 ResourceBundle 的完全限定类名。有关资源包名称语法的更多信息，请参见 java.util.ResourceBundle 类的 JavaDocs。

bundle	要使用的资源包的基本名称
Throws	NullPointerException: 如果 bundle 为 null

英文文档：

setMessageBundle

public abstract void setMessageBundle(String bundle)

Set the fully qualified class name of the ResourceBundle to be used for JavaServer Faces messages for this application. See the JavaDocs for the java.util.ResourceBundle class for more information about the syntax for resource bundle names.

Parameters:

bundle - Base name of the resource bundle to be used

Throws:

NullPointerException - if bundle is null

abstract public NavigationHandler getNavigationHandler()

返回 NavigationHandler 实例，将向该实例传递此 Web 应用程序任何调用的应用程序操作返回的结果。如果没有显式设置，则必须提供执行 NavigationHandler 类描述中所述函数的默认实现。

英文文档：

getNavigationHandler

public abstract NavigationHandler getNavigationHandler()

Return the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application. If not explicitly set, a default implementation must be provided that performs the functions described in the NavigationHandler class description.

abstract public void setNavigationHandler(NavigationHandler handler)

设置 NavigationHandler 实例，将向该实例传递此 Web 应用程序任何调用的应用程序操作返回的结果。

handler	新 NavigationHandler 实例
Throws	NullPointerException: 如果 handler 为 null

英文文档：

setNavigationHandler

public abstract void setNavigationHandler(NavigationHandler handler)

Set the NavigationHandler instance that will be passed the outcome returned by any invoked application action for this web application.

Parameters:

handler - The new NavigationHandler instance

Throws:

NullPointerException - if handler is null

abstract public PropertyResolver getPropertyResolver()

返回包装 ELResolver 实例的 PropertyResolver 实例，Faces 将 ELResolver 实例提供给统一 EL，用于解析应用程序中以编程方式出现的表达式。

注意，这种情况不再返回默认 PropertyResolver，因为该类现在是帮助使自定义 PropertyResolver 影响 EL 解析过程的无操作 (no-op)。

deprecated

此方法已由 #getELResolver 替代。

英文文档：

getPropertyResolver

public abstract PropertyResolver getPropertyResolver()

Deprecated. This has been replaced by getELResolver().

Return a PropertyResolver instance that wraps the ELResolver instance that Faces provides to the unified EL for the resolution of expressions that appear programmatically in an application.

Note that this no longer returns the default PropertyResolver since that class is now a no-op that aids in allowing custom PropertyResolvers to affect the EL resolution process.

abstract public void setPropertyResolver(PropertyResolver resolver)

设置将用于解析方法和值绑定的 PropertyResolver 实例。

此方法现在已过时，但其实现必须使参数设置为遗留 PropertyResolver 链的头，替换在应用程序配置资源中设置的任何现有值。

应用程序从客户端收到请求后调用此方法是非法的。如果尝试在此之后注册侦听器，则没有任何效果。

resolver	新 PropertyResolver 实例
Throws	NullPointerException: 如果 resolver 为 null
deprecated	影响 EL 执行的建议方法是，在应用程序配置资源的正确位置提供 <el-resolver> 元素，这些资源将在正常的表达式求值过程中予以考虑。此方法现在将导致在 ELResolver 的实现中包装参数 resolver 并向 EL 解析系统公开，就像用户已调用 #addELResolver 一样。
Throws	IllegalStateException: 如果在处理了第一个对 javax.faces.webapp.FacesServlet 的请求之后调用。

英文文档：

setPropertyResolver

public abstract void setPropertyResolver(PropertyResolver resolver)

Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).

Set the PropertyResolver instance that will be utilized to resolve method and value bindings.

This method is now deprecated but the implementation must cause the argument to be set as the head of the legacy PropertyResolver chain, replacing any existing value that was set from the application configuration resources.

It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.

Parameters:

resolver - The new PropertyResolver instance

Throws:

NullPointerException - if resolver is null

IllegalStateException - if called after the first request to the FacesServlet has been serviced.

public java.util.ResourceBundle getResourceBundle(FacesContext ctx, String name)

查找在应用程序配置资源中以指定名称定义的 ResourceBundle。如果定义了该名称的 ResourceBundle，则返回使用当前 javax.faces.component.UIViewRoot 的语言环境的实例。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展此类的现有应用程序。

return	当前 UIViewRoot 的 ResourceBundle，否则返回 null
Throws	FacesException: 如果定义了包，但该包不可解析
Throws	NullPointerException: 如果 ctx == null || name == null
since	1.2

英文文档：

getResourceBundle

public ResourceBundle getResourceBundle(FacesContext ctx,
                                        String name)

Find a ResourceBundle as defined in the application configuration resources under the specified name. If a ResourceBundle was defined for the name, return an instance that uses the locale of the current UIViewRoot.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend this class.

Returns:

ResourceBundle for the current UIViewRoot, otherwise null

Throws:

FacesException - if a bundle was defined, but not resolvable

NullPointerException - if ctx == null || name == null

Since:

1.2

abstract public VariableResolver getVariableResolver()

返回包装 ELResolver 实例的 VariableResolver，Faces 将 ELResolver 实例提供给统一 EL，用于解析应用程序中以编程方式出现的表达式。VariableResolver 的实现必须将 null 作为基参数传递给在底层 ELResolver 上调用的任何方法。

注意，此方法不再返回默认 VariableResolver，因为该类现在是帮助使自定义 VariableResolver 影响 EL 解析过程的无操作。

deprecated

此方法已由 #getELResolver 替代。

英文文档：

getVariableResolver

public abstract VariableResolver getVariableResolver()

Deprecated. This has been replaced by getELResolver().

Return the VariableResolver that wraps the ELResolver instance that Faces provides to the unified EL for the resolution of expressions that appear programmatically in an application. The implementation of the VariableResolvermust pass null as the base argument for any methods invoked on the underlying ELResolver.

Note that this method no longer returns the default VariableResolver, since that class now is a no-op that aids in allowing custom VariableResolvers to affect the EL resolution process.

abstract public void setVariableResolver(VariableResolver resolver)

设置将用于解析方法和值绑定的 VariableResolver 实例。

此方法现在已过时，但其实现必须使参数设置为遗留 VariableResolver 链的头，替换在应用程序配置资源中设置的任何现有值。

应用程序从客户端收到请求后调用此方法是非法的。如果尝试在此之后注册侦听器，则没有任何效果。

resolver	新 VariableResolver 实例
Throws	NullPointerException: 如果 resolver 为 null
deprecated	影响 EL 执行的建议方法是，在应用程序配置资源的正确位置提供 <el-resolver> 元素， 这些资源将在正常的表达式求值过程中予以考虑。此方法现在将导致在 ELResolver 的实现中包装参数 resolver 并向 EL 解析系统公开，就像用户已调用 #addELResolver 一样。
Throws	IllegalStateException: 如果在处理了第一个对 javax.faces.webapp.FacesServlet 的请求之后调用。

英文文档：

setVariableResolver

public abstract void setVariableResolver(VariableResolver resolver)

Deprecated. The recommended way to affect the execution of the EL is to provide an <el-resolver> element at the right place in the application configuration resources which will be considered in the normal course of expression evaluation. This method now will cause the argument resolver to be wrapped inside an implementation of ELResolver and exposed to the EL resolution system as if the user had called addELResolver(javax.el.ELResolver).

Set the VariableResolver instance that will be consulted to resolve method and value bindings.

This method is now deprecated but the implementation must cause the argument to be set as the head of the legacy VariableResolver chain, replacing any existing value that was set from the application configuration resources.

It is illegal to call this method after the application has received any requests from the client. If an attempt is made to register a listener after that time it must have no effect.

Parameters:

resolver - The new VariableResolver instance

Throws:

NullPointerException - if resolver is null

IllegalStateException - if called after the first request to the FacesServlet has been serviced.

public void addELResolver(ELResolver resolver)

使参数 resolver 被添加到 JavaServer Faces 规范的 5.5.1 节中指定的解析器链。

在注册了 ELResolver 后，无法移除使用此方法注册的 ELResolver。

应用程序从客户端收到请求后注册 ELResolver 是非法的。如果尝试在此之后注册侦听器，则必定抛出 IllegalStateException。在链中除标准 ELResolver 外没有其他 ELResolver 的一般情况下，此限制可适当地使 JSP 容器得到优化。允许在初始化链中已存在的 CompositeELResolver 之前或之后添加 ELResolver。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展 Application 的现有应用程序。

since

1.2

英文文档：

addELResolver

public void addELResolver(ELResolver resolver)

Cause an the argument resolver to be added to the resolver chain as specified in section 5.5.1 of the JavaServer Faces Specification.

It is not possible to remove an ELResolver registered with this method, once it has been registered.

It is illegal to register an ELResolver after the application has received any requests from the client. If an attempt is made to register a listener after that time, an IllegalStateException must be thrown. This restriction is in place to allow the JSP container to optimize for the common case where no additional ELResolvers are in the chain, aside from the standard ones. It is permissible to add ELResolvers before or after initialization to a CompositeELResolver that is already in the chain.

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend Application.

Since:

1.2

public ELResolver getELResolver()

返回要用于所有 EL 解析的单件 ELResolver 实例。这实际上是一个 javax.el.CompositeELResolver 实例，它必须按以下顺序包含下列 ELResolver 实例：

1. 在应用程序配置资源中使用 <el-resolver> 元素声明的 ELResolver 实例。

2. 根据规范文档第 5 章 VariableResolver ChainWrapper 一节所述，包装遗留 VariableResolver 链头的 implementation。

3. 根据规范文档第 5 章 PropertyResolver ChainWrapper 一节所述，包装遗留 PropertyResolver 链头的 implementation。

4. 通过调用 #addELResolver 添加的任何 ELResolver 实例。

默认实现抛出 UnsupportedOperationException，提供它只有一个目的，即不破坏扩展 Application 的现有应用程序。

since

1.2

英文文档：

getELResolver

public ELResolver getELResolver()

Return the singleton ELResolver instance to be used for all EL resolution. This is actually an instance of CompositeELResolver that must contain the following ELResolver instances in the following order:

1. ELResolver instances declared using the <el-resolver> element in the application configuration resources.

2. An implementation that wraps the head of the legacy VariableResolver chain, as per section VariableResolver ChainWrapper in Chapter 5 in the spec document.

3. An implementation that wraps the head of the legacy PropertyResolver chain, as per section PropertyResolver ChainWrapper in Chapter 5 in the spec document.

4. Any ELResolver instances added by calls to addELResolver(javax.el.ELResolver).

The default implementation throws UnsupportedOperationException and is provided for the sole purpose of not breaking existing applications that extend Application.

Since:

1.2

abstract public ViewHandler getViewHandler()

返回将在请求处理生命周期的恢复视图 和呈现响应 阶段使用的 ViewHandler 实例。如果没有显式设置，则必须提供执行 JavaServer Faces 规范中 ViewHandler 描述中所述函数的默认实现。

英文文档：

getViewHandler

public abstract ViewHandler getViewHandler()

Return the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle. If not explicitly set, a default implementation must be provided that performs the functions described in the ViewHandler description in the JavaServer Faces Specification.

abstract public void setViewHandler(ViewHandler handler)

设置将在请求处理生命周期的恢复视图 和呈现响应 阶段使用的 ViewHandler 实例。

handler	新 ViewHandler 实例
Throws	IllegalStateException: 如果此应用程序的 Lifecycle 实例至少处理了一个请求后调用此方法。
Throws	NullPointerException: 如果 handler 为 null

英文文档：

setViewHandler

public abstract void setViewHandler(ViewHandler handler)

Set the ViewHandler instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.

Parameters:

handler - The new ViewHandler instance

Throws:

IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.

NullPointerException - if handler is null

abstract public StateManager getStateManager()

返回将在请求处理生命周期的恢复视图 和呈现响应 阶段使用的 StateManager 实例。如果没有显式设置，则必须提供执行 JavaServer Faces 规范中 StateManager 描述中所述函数的默认实现。

英文文档：

getStateManager

public abstract StateManager getStateManager()

Return the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle. If not explicitly set, a default implementation must be provided that performs the functions described in the StateManager description in the JavaServer Faces Specification.

abstract public void setStateManager(StateManager manager)

设置将在请求处理生命周期的恢复视图 和呈现响应 阶段使用的 StateManager 实例。

manager	新 StateManager 实例
Throws	IllegalStateException: 如果此应用程序的 Lifecycle 实例至少处理了一个请求后调用此方法。
Throws	NullPointerException: 如果 manager 为 null

英文文档：

setStateManager

public abstract void setStateManager(StateManager manager)

Set the StateManager instance that will be utilized during the Restore View and Render Response phases of the request processing lifecycle.

Parameters:

manager - The new StateManager instance

Throws:

IllegalStateException - if this method is called after at least one request has been processed by the Lifecycle instance for this application.

NullPointerException - if manager is null

abstract public void addComponent(String componentType, String componentClass)

注册组件类型到相应 UIComponent 类名称的新映射。这使得后续对 createComponent() 的调用可作为 UIComponent 实例的工厂。

componentType	要注册的组件类型
componentClass	相应 UIComponent 实现的完全限定类名
Throws	NullPointerException: 如果 componentType 或 componentClass 为 null

英文文档：

addComponent

public abstract void addComponent(String componentType,
                                  String componentClass)

Register a new mapping of component type to the name of the corresponding UIComponent class. This allows subsequent calls to createComponent() to serve as a factory for UIComponent instances.

Parameters:

componentType - The component type to be registered

componentClass - The fully qualified class name of the corresponding UIComponent implementation

Throws:

NullPointerException - if componentType or componentClass is null

abstract public UIComponent createComponent(String componentType) throws FacesException

实例化并返回类的新 UIComponent 实例，该类是通过以前为指定组件类型调用 addComponent() 指定的。

componentType	要为其创建并返回新 UIComponent 实例的组件类型
Throws	FacesException: 如果无法创建指定类型的 UIComponent
Throws	NullPointerException: 如果 componentType 为 null

英文文档：

createComponent

public abstract UIComponent createComponent(String componentType)
                                     throws FacesException

Instantiate and return a new UIComponent instance of the class specified by a previous call to addComponent() for the specified component type.

Parameters:

componentType - The component type for which to create and return a new UIComponent instance

Throws:

FacesException - if a UIComponent of the specified type cannot be created

NullPointerException - if componentType is null

abstract public UIComponent createComponent(ValueBinding componentBinding, FacesContext context, String componentType) throws FacesException

在 ValueExpression 的实现中包装参数 componentBinding 并调用 #createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String)。

componentBinding	表示组件值绑定表达式（通常由自定义标记的 component 属性指定）的 ValueBinding
context	当前请求的 FacesContext
componentType	要创建的组件类型（如果 ValueBinding 没有返回组件实例）
Throws	FacesException: 如果无法创建 UIComponent
Throws	NullPointerException: 如果有参数为 null
deprecated	此方法已由 #createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String) 替代。

英文文档：

createComponent

public abstract UIComponent createComponent(ValueBinding componentBinding,
                                            FacesContext context,
                                            String componentType)
                                     throws FacesException

Deprecated. This has been replaced by createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).

Wrap the argument componentBinding in an implementation of ValueExpression and call through to createComponent(javax.el.ValueExpression,javax.faces.context.FacesContext,java.lang.String).

Parameters:

componentBinding - ValueBinding representing a component value binding expression (typically specified by the component attribute of a custom tag)

context - FacesContext for the current request

componentType - Component type to create if the ValueBinding does not return a component instance

Throws:

FacesException - if a UIComponent cannot be created

NullPointerException - if any parameter is null

public UIComponent createComponent(ValueExpression componentExpression, FacesContext context, String componentType) throws FacesException

对指定的 ValueExpression 调用 getValue() 方法。如果它返回 UIComponent 实例，则将其作为此方法的值返回。如果它没有返回 UIComponent 实例，则实例化指定组件类型的新 UIComponent 实例，将新组件传递给指定 ValueExpression 的 setValue() 方法，然后将其作为此方法的值返回。

componentExpression	表示组件值表达式（通常由自定义标记的 component 属性指定）的 ValueExpression
context	当前请求的 FacesContext
componentType	要创建的组件类型（如果 ValueExpression 没有返回组件实例）
Throws	FacesException: 如果无法创建 UIComponent
Throws	NullPointerException: 如果有参数为 null 提供一个抛出 UnsupportedOperationException 的默认实现，以便装饰 Application 的用户能够继续工作。 .
since	1.2

英文文档：

createComponent

public UIComponent createComponent(ValueExpression componentExpression,
                                   FacesContext context,
                                   String componentType)
                            throws FacesException

Call the getValue() method on the specified ValueExpression. If it returns a UIComponent instance, return it as the value of this method. If it does not, instantiate a new UIComponent instance of the specified component type, pass the new component to the setValue() method of the specified ValueExpression, and return it.

Parameters:

componentExpression - ValueExpression representing a component value expression (typically specified by the component attribute of a custom tag)

context - FacesContext for the current request

componentType - Component type to create if the ValueExpression does not return a component instance

Throws:

FacesException - if a UIComponent cannot be created

NullPointerException - if any parameter is null

A default implementation is provided that throws UnsupportedOperationException so that users that decorate Application can continue to function

.

Since:

1.2

abstract public java.util.Iterator<E> getComponentTypes()

返回此 Application 当前定义的组件类型集合上的 Iterator。

英文文档：

getComponentTypes

public abstract Iterator<String> getComponentTypes()

Return an Iterator over the set of currently defined component types for this Application.

abstract public void addConverter(String converterId, String converterClass)

注册转换器 ID 到相应 Converter 类名称的新映射。这使得后续对 createConverter() 的调用可作为 Converter 实例的工厂。

converterId	要注册的转换器 ID
converterClass	相应 Converter 实现的完全限定类名
Throws	NullPointerException: 如果 converterId 或 converterClass 为 null

英文文档：

addConverter

public abstract void addConverter(String converterId,
                                  String converterClass)

Register a new mapping of converter id to the name of the corresponding Converter class. This allows subsequent calls to createConverter() to serve as a factory for Converter instances.

Parameters:

converterId - The converter id to be registered

converterClass - The fully qualified class name of the corresponding Converter implementation

Throws:

NullPointerException - if converterId or converterClass is null

abstract public void addConverter(Class<T> targetClass, String converterClass)

注册能够对指定目标类执行转换的新转换器类。

targetClass	为其注册此转换器的类
converterClass	相应 Converter 实现的完全限定类名
Throws	NullPointerException: 如果 targetClass 或 converterClass 为 null

英文文档：

addConverter

public abstract void addConverter(Class targetClass,
                                  String converterClass)

Register a new converter class that is capable of performing conversions for the specified target class.

Parameters:

targetClass - The class for which this converter is registered

converterClass - The fully qualified class name of the corresponding Converter implementation

Throws:

NullPointerException - if targetClass or converterClass is null

abstract public Converter createConverter(String converterId)

实例化并返回类的新 Converter 实例，该类是通过以前为指定转换器 ID 调用 addConverter() 指定的。如果此转换器 ID 没有这样的注册，则返回 null。

converterId	要为其创建并返回新 Converter 实例的转换器 ID
Throws	FacesException: 如果无法创建 Converter
Throws	NullPointerException: 如果 converterId 为 null

英文文档：

createConverter

public abstract Converter createConverter(String converterId)

Instantiate and return a new Converter instance of the class specified by a previous call to addConverter() for the specified converter id. If there is no such registration for this converter id, return null.

Parameters:

converterId - The converter id for which to create and return a new Converter instance

Throws:

FacesException - if the Converter cannot be created

NullPointerException - if converterId is null

abstract public Converter createConverter(Class<T> targetClass)

实例化并返回类的新 Converter 实例，该类已将自身注册为可以为指定类型的对象执行转换。如果不能识别这样的 Converter 类，则返回 null。

要定位到适当的 Converter 类，执行以下算法，在找到适当的 Converter 类后停止：

• 定位到为目标类本身注册的 Converter。
• 定位到为目标类（直接或间接）实现的接口注册的 Converter。
• 在继承层次结构中以递归方式定位到为目标类的超类（如果有）注册的 Converter。

如果 Converter 有一个接受 Class 的参数构造方法，则使用该构造方法实例化 Converter，同时将参数 targetClass 作为唯一参数传递。否则，只需使用不带参数的构造方法即可。

targetClass	要为其返回 Converter 的目标类
Throws	FacesException: 如果无法创建 Converter
Throws	NullPointerException: 如果 targetClass 为 null

英文文档：

createConverter

public abstract Converter createConverter(Class targetClass)

Instantiate and return a new Converter instance of the class that has registered itself as capable of performing conversions for objects of the specified type. If no such Converter class can be identified, return null.

To locate an appropriate Converter class, the following algorithm is performed, stopping as soon as an appropriate Converter class is found:

• Locate a Converter registered for the target class itself.
• Locate a Converter registered for interfaces that are implemented by the target class (directly or indirectly).
• Locate a Converter registered for the superclass (if any) of the target class, recursively working up the inheritance hierarchy.

If the Converter has a single argument constructor that accepts a Class, instantiate the Converter using that constructor, passing the argument targetClass as the sole argument. Otherwise, simply use the zero-argument constructor.

Parameters:

targetClass - Target class for which to return a Converter

Throws:

FacesException - if the Converter cannot be created

NullPointerException - if targetClass is null

abstract public java.util.Iterator<E> getConverterIds()

返回此 Application 当前注册的转换器 ID 集合上的 Iterator。

英文文档：

getConverterIds

public abstract Iterator<String> getConverterIds()

Return an Iterator over the set of currently registered converter ids for this Application.

abstract public java.util.Iterator<E> getConverterTypes()

返回已为其显式注册 Converter 类的 Class 实例集合上的 Iterator。

英文文档：

getConverterTypes

public abstract Iterator<Class> getConverterTypes()

Return an Iterator over the set of Class instances for which Converter classes have been explicitly registered.

public ExpressionFactory getExpressionFactory()

返回此应用程序的 ExpressionFactory 实例。此实例由便捷方法 #evaluateExpressionGet 使用。

此实现必须通过调用 JspFactory.getDefaultFactory().getJspApplicationContext(servletContext).getExpressionFactory() 从 JSP 容器返回 ExpressionFactory。

提供一个抛出 UnsupportedOperationException 的实现，以便装饰 Application 的用户能够继续工作。

since

1.2

英文文档：

getExpressionFactory

public ExpressionFactory getExpressionFactory()

Return the ExpressionFactory instance for this application. This instance is used by the convenience method evaluateExpressionGet(javax.faces.context.FacesContext, java.lang.String, java.lang.Class).

The implementation must return the ExpressionFactory from the JSP container by calling JspFactory.getDefaultFactory().getJspApplicationContext(servletContext).getExpressionFactory().

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

public Object evaluateExpressionGet(FacesContext context, String expression, Class<T> expectedType) throws ELException

通过求表达式的值来获取值。

调用 #getExpressionFactory，然后调用 ExpressionFactory#createValueExpression，同时传递参数 expression 和 expectedType。调用 FacesContext#getELContext 并将其传递给 ValueExpression#getValue，同时返回结果。

提供一个抛出 UnsupportedOperationException 的实现，以便装饰 Application 的用户能够继续工作。

英文文档：

evaluateExpressionGet

public Object evaluateExpressionGet(FacesContext context,
                                    String expression,
                                    Class expectedType)
                             throws ELException

Get a value by evaluating an expression.

Call getExpressionFactory() then call ExpressionFactory.createValueExpression(javax.el.ELContext, java.lang.String, java.lang.Class) passing the argument expression and expectedType. Call FacesContext.getELContext() and pass it to ValueExpression.getValue(javax.el.ELContext), returning the result.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Throws:

ELException

abstract public MethodBinding createMethodBinding(String ref, Class<T>[] params) throws ReferenceSyntaxException

调用 #getExpressionFactory，然后调用 ExpressionFactory#createMethodExpression，同时传递给定参数，然后在 MethodBinding 实现中包装结果，同时返回结果。

ref	为其返回 MethodBinding 实例的方法绑定表达式
params	必须与要调用的方法的那些参数签名兼容的参数签名，或者对不带参数的方法而言，为长度为 0 的数组或 null
Throws	NullPointerException: 如果 ref 为 null
Throws	ReferenceSyntaxException: 如果指定的 ref 存在无效的语法
deprecated	此方法已通过调用 #getExpressionFactory，然后调用 ExpressionFactory#createMethodExpression 替代。

英文文档：

createMethodBinding

public abstract MethodBinding createMethodBinding(String ref,
                                                  Class[] params)
                                           throws ReferenceSyntaxException

Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory.createMethodExpression(javax.el.ELContext, java.lang.String, java.lang.Class, java.lang.Class[]).

Call getExpressionFactory() then call ExpressionFactory.createMethodExpression(javax.el.ELContext, java.lang.String, java.lang.Class, java.lang.Class[]), passing the given arguments, and wrap the result in a MethodBinding implementation, returning it.

Parameters:

ref - Method binding expression for which to return a MethodBinding instance

params - Parameter signatures that must be compatible with those of the method to be invoked, or a zero-length array or null for a method that takes no parameters

Throws:

NullPointerException - if ref is null

ReferenceSyntaxException - if the specified ref has invalid syntax

abstract public java.util.Iterator<E> getSupportedLocales()

返回此应用程序支持的 Locale 上的 Iterator。

英文文档：

getSupportedLocales

public abstract Iterator<Locale> getSupportedLocales()

Return an Iterator over the supported Locales for this appication.

英文文档：

setSupportedLocales

public abstract void setSupportedLocales(Collection<Locale> locales)

Set the Locale instances representing the supported Locales for this application.

Parameters:

locales - The set of supported Locales for this application

Throws:

NullPointerException - if the argument newLocales is null.

public void addELContextListener(ELContextListener listener)

为 Faces 应用程序提供注册 ELContextListener 的方法，在创建 ELContext 实例时将通知此侦听器。每个请求只应调用此侦听器一次。

提供一个抛出 UnsupportedOperationException 的实现，以便装饰 Application 的用户能够继续工作。

since

1.2

英文文档：

addELContextListener

public void addELContextListener(ELContextListener listener)

Provide a way for Faces applications to register an ELContextListener that will be notified on creation of ELContext instances. This listener will be called once per request.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

public void removeELContextListener(ELContextListener listener)

从 ELContextListener 列表中移除参数 listener。如果 listener 为 null，则不抛出任何异常并且不执行任何操作。如果 listener 不在列表中，则不抛出任何异常并且不执行任何操作。

提供一个抛出 UnsupportedOperationException 的实现，以便装饰 Application 的用户能够继续工作。

since

1.2

英文文档：

removeELContextListener

public void removeELContextListener(ELContextListener listener)

Remove the argument listener from the list of ELContextListeners. If listener is null, no exception is thrown and no action is performed. If listener is not in the list, no exception is thrown and no action is performed.

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

public ELContextListener[] getELContextListeners()

如果没有调用过 #addELContextListener，则此方法必须返回空数组。

否则，返回表示通过调用 #addELContextListener 添加的侦听器列表的数组。

提供一个抛出 UnsupportedOperationException 的实现，以便装饰 Application 的用户能够继续工作。

since

1.2

英文文档：

getELContextListeners

public ELContextListener[] getELContextListeners()

If no calls have been made to addELContextListener(javax.el.ELContextListener), this method must return an empty array.

Otherwise, return an array representing the list of listeners added by calls to addELContextListener(javax.el.ELContextListener).

An implementation is provided that throws UnsupportedOperationException so that users that decorate the Application continue to work.

Since:

1.2

abstract public void addValidator(String validatorId, String validatorClass)

注册验证器 ID 到相应 Validator 类名称的新映射。这使得后续对 createValidator() 的调用可作为 Validator 实例的工厂。

validatorId	要注册的验证器 ID
validatorClass	相应 Validator 实现的完全限定类名
Throws	NullPointerException: 如果 validatorId 或 validatorClass 为 null

英文文档：

addValidator

public abstract void addValidator(String validatorId,
                                  String validatorClass)

Register a new mapping of validator id to the name of the corresponding Validator class. This allows subsequent calls to createValidator() to serve as a factory for Validator instances.

Parameters:

validatorId - The validator id to be registered

validatorClass - The fully qualified class name of the corresponding Validator implementation

Throws:

NullPointerException - if validatorId or validatorClass is null

abstract public Validator createValidator(String validatorId) throws FacesException

实例化并返回类的新 Validator 实例，该类是通过以前为指定验证器 ID 调用 addValidator() 指定的。

validatorId	要为其创建并返回新 Validator 实例的验证器 ID
Throws	FacesException: 如果无法创建指定 ID 的 Validator
Throws	NullPointerException: 如果 validatorId 为 null

英文文档：

createValidator

public abstract Validator createValidator(String validatorId)
                                   throws FacesException

Instantiate and return a new Validator instance of the class specified by a previous call to addValidator() for the specified validator id.

Parameters:

validatorId - The validator id for which to create and return a new Validator instance

Throws:

FacesException - if a Validator of the specified id cannot be created

NullPointerException - if validatorId is null

abstract public java.util.Iterator<E> getValidatorIds()

返回此 Application 当前注册的验证器 ID 集合上的 Iterator。

英文文档：

getValidatorIds

public abstract Iterator<String> getValidatorIds()

Return an Iterator over the set of currently registered validator ids for this Application.

abstract public ValueBinding createValueBinding(String ref) throws ReferenceSyntaxException

调用 #getExpressionFactory，然后调用 ExpressionFactory#createValueExpression，同时传递参数 ref（为 expectedType 传递 Object.class，为 fnMapper 传递 null）。

ref	要为其返回 ValueBinding 实例的值绑定表达式
Throws	NullPointerException: 如果 ref 为 null
Throws	ReferenceSyntaxException: 如果指定的 ref 存在无效的语法
deprecated	此方法已通过调用 #getExpressionFactory，然后调用 ExpressionFactory#createValueExpression 替代。

英文文档：

createValueBinding

public abstract ValueBinding createValueBinding(String ref)
                                         throws ReferenceSyntaxException

Deprecated. This has been replaced by calling getExpressionFactory() then ExpressionFactory.createValueExpression(javax.el.ELContext, java.lang.String, java.lang.Class).

Call getExpressionFactory() then call ExpressionFactory.createValueExpression(javax.el.ELContext, java.lang.String, java.lang.Class), passing the argument ref, Object.class for the expectedType, and null, for the fnMapper.

Parameters:

ref - Value binding expression for which to return a ValueBinding instance

Throws:

NullPointerException - if ref is null

ReferenceSyntaxException - if the specified ref has invalid syntax

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