FactoryFinder (Java EE 5)

FactoryFinder 实现 JavaServer Faces API 中指定的所有工厂对象的标准发现算法。对于给定的工厂类名，将根据以下算法搜索相应的实现类。各条目以递减的搜索优先顺序列出：

• 如果 JavaServer Faces 配置文件（绑定到 Web 应用程序的 WEB-INF 目录）包含具有给定工厂类名称的 factory 条目，则使用该工厂。
• 如果 javax.faces.CONFIG_FILES ServletContext init 参数指定的 JavaServer Faces 配置文件包含任何具有给定工厂类名称的 factory 条目，则使用这些工厂（最后一个优先使用）。
• 如果有任何 JavaServer Faces 配置文件绑定到 ServletContext 的资源路径上的任何 jar 文件的 META-INF 目录，则使用这些文件中具有给定工厂类名称的 factory 条目（最后一个优先使用）。
• 如果 META-INF/services/{factory-class-name} 资源对于调用它的应用程序的 Web 应用程序类加载器是可见的（通常是因为出现在一个 JAR 文件的清单中），则将读取第一行并将其视为要使用的工厂实现类的名称。
• 如果以上步骤都没有得到匹配项，则使用 JavaServer Faces 实现特有的类。

如果以上任何步骤中发现的任何工厂碰巧拥有单参数的构造方法，并且参数类型为抽象工厂类，则调用该构造方法，并将前面的匹配项传递给该构造方法。例如，假设容器供应商提供了 javax.faces.context.FacesContextFactory 实现，并在 Web 应用程序 ClassLoader 的 jar 文件的 META-INF/services/javax.faces.context.FacesContextFactory 中标识。同时假设容器供应商提供的这个实现拥有单参数的构造方法，并且该方法接受 FacesContextFactory 实例。那么 FactoryFinder 系统将调用这个单参数构造方法，同时传递 JavaServer Faces 实现提供的 FacesContextFactory 实现。

如果 Factory 实现没有提供相应的单参数构造方法，则它必须提供无参数构造方法，以便成功进行实例化。

找到工厂实现类的名称后，将请求调用它的应用程序的 Web 应用程序类加载器加载此类，然后创建该类的相应实例。此规则的副作用是，不管 JavaServer Faces 实现是包含在 Web 应用程序中还是通过容器的共享库工具变得可见，每个 Web 应用程序都将收到各自的工厂类实例。

FactoryFinder implements the standard discovery algorithm for all factory objects specified in the JavaServer Faces APIs. For a given factory class name, a corresponding implementation class is searched for based on the following algorithm. Items are listed in order of decreasing search precedence:

• If the JavaServer Faces configuration file bundled into the WEB-INF directory of the webapp contains a factory entry of the given factory class name, that factory is used.
• If the JavaServer Faces configuration files named by the javax.faces.CONFIG_FILES ServletContext init parameter contain any factory entries of the given factory class name, those factories are used, with the last one taking precedence.
• If there are any JavaServer Faces configuration files bundled into the META-INF directory of any jars on the ServletContext's resource paths, the factory entries of the given factory class name in those files are used, with the last one taking precedence.
• If a META-INF/services/{factory-class-name} resource is visible to the web application class loader for the calling application (typically as a result of being present in the manifest of a JAR file), its first line is read and assumed to be the name of the factory implementation class to use.
• If none of the above steps yield a match, the JavaServer Faces implementation specific class is used.

If any of the factories found on any of the steps above happen to have a one-argument constructor, with argument the type being the abstract factory class, that constructor is invoked, and the previous match is passed to the constructor. For example, say the container vendor provided an implementation of FacesContextFactory, and identified it in META-INF/services/javax.faces.context.FacesContextFactory in a jar on the webapp ClassLoader. Also say this implementation provided by the container vendor had a one argument constructor that took a FacesContextFactory instance. The FactoryFinder system would call that one-argument constructor, passing the implementation of FacesContextFactory provided by the JavaServer Faces implementation.

If a Factory implementation does not provide a proper one-argument constructor, it must provide a zero-arguments constructor in order to be successfully instantiated.

Once the name of the factory implementation class is located, the web application class loader for the calling application is requested to load this class, and a corresponding instance of the class will be created. A side effect of this rule is that each web application will receive its own instance of each factory class, whether the JavaServer Faces implementation is included within the web application or is made visible through the container's facilities for shared libraries.

英文文档：

APPLICATION_FACTORY

public static final String APPLICATION_FACTORY

The property name for the ApplicationFactory class name.

See Also:

Constant Field Values

英文文档：

FACES_CONTEXT_FACTORY

public static final String FACES_CONTEXT_FACTORY

The property name for the FacesContextFactory class name.

See Also:

Constant Field Values

英文文档：

LIFECYCLE_FACTORY

public static final String LIFECYCLE_FACTORY

The property name for the LifecycleFactory class name.

See Also:

Constant Field Values

英文文档：

RENDER_KIT_FACTORY

public static final String RENDER_KIT_FACTORY

The property name for the RenderKitFactory class name.

See Also:

Constant Field Values

public static Object getFactory(String factoryName) throws FacesException

根据指定 JavaServer Faces 工厂类相应的实现类描述中所述的发现算法，创建（如有必要）并返回该类的实例（每个 Web 应用程序一个实例）。

factoryName	请求实现实例的 JavaServer Faces 工厂的完全限定名
Throws	FacesException: 如果无法识别 Web 应用程序类加载器
Throws	FacesException: 如果无法加载配置的工厂实现类的实例
Throws	FacesException: 如果无法初始化配置的工厂实现类的实例
Throws	IllegalArgumentException: 如果 factoryName 无法识别标准的 JavaServer Faces 工厂名
Throws	IllegalStateException: 如果指定的工厂名称没有配置工厂实现类
Throws	NullPointerException: 如果 factoryname 为 null

英文文档：

getFactory

public static Object getFactory(String factoryName)
                         throws FacesException

Create (if necessary) and return a per-web-application instance of the appropriate implementation class for the specified JavaServer Faces factory class, based on the discovery algorithm described in the class description.

Parameters:

factoryName - Fully qualified name of the JavaServer Faces factory for which an implementation instance is requested

Throws:

FacesException - if the web application class loader cannot be identified

FacesException - if an instance of the configured factory implementation class cannot be loaded

FacesException - if an instance of the configured factory implementation class cannot be instantiated

IllegalArgumentException - if factoryName does not identify a standard JavaServer Faces factory name

IllegalStateException - if there is no configured factory implementation class for the specified factory name

NullPointerException - if factoryname is null

public static void setFactory(String factoryName, String implName)

此方法将以便于 #getFactory 搜索匹配项时发现该映射的方式存储参数 factoryName/implName 映射。

如果已调用 getFactory() 查找此 factoryName 对应的工厂，则此方法没有任何效果。

此方法可以被实现用来在解析 Faces 配置文件时存储工厂映射。

Throws	IllegalArgumentException: 如果 factoryName 无法识别标准的 JavaServer Faces 工厂名
Throws	NullPointerException: 如果 factoryname 为 null

英文文档：

setFactory

public static void setFactory(String factoryName,
                              String implName)

This method will store the argument factoryName/implName mapping in such a way that getFactory(java.lang.String) will find this mapping when searching for a match.

This method has no effect if getFactory() has already been called looking for a factory for this factoryName.

This method can be used by implementations to store a factory mapping while parsing the Faces configuration file

Throws:

IllegalArgumentException - if factoryName does not identify a standard JavaServer Faces factory name

NullPointerException - if factoryname is null

public static void releaseFactories() throws FacesException

释放所有对调用它的 Web 应用程序的类加载器所关联的工厂实例的引用。如果容器中的 JavaServer Faces API 类是容器本身的一部分，而不是包含在 Web 应用程序内部，则调用此方法应该是 Web 应用程序终止过程的一部分。

Throws

FacesException: 如果无法识别 Web 应用程序类加载器

英文文档：

releaseFactories

public static void releaseFactories()
                             throws FacesException

Release any references to factory instances associated with the class loader for the calling web application. This method should be called as apart of web application shutdown in a container where the JavaServer Faces API classes are part of the container itself, rather than being included inside the web application.

Throws:

FacesException - if the web application class loader cannot be identified

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