ELResolver (Java EE 5)

对一个表达式进行求值时，参考与 ELContext 关联的 ELResolver，以对表达式的第一个变量进行初始解析。遇到 . 或 [] 操作符时也要参考它，但方法表达式中最后一个这样的操作符除外，因为在这种情况下解析规则是固定编码的。

例如，在 EL 表达式 ${employee.lastName} 中，ELResolver 确定 employee 引用的对象，以及获取该对象 lastName 属性的含义。

此类中的大多数方法都接受 base 和 property 参数。如果是变量解析（例如，确定 ${employee.lastName} 中 employee 引用的内容），则 base 参数将为 null，property 参数将总是为 String 类型。这种情况下，如果 property 不是 String，则 ELResolver 的行为未定义。

如果是属性解析，则 base 参数标识 base 对象，property 对象标识 base 上的属性。例如，在表达式 ${employee.lastName} 中，base 是 employee 变量解析的结果，property 是字符串 "lastName"。在表达式 ${y[x]} 中，base 是 y 变量解析的结果，property 是 x 变量解析的结果。

尽管只有一个 ELResolver 与 ELContext 关联，但对于任何给定的变量或属性解析，通常可以使用多个解析器。ELResolver 使用 CompositeELResolver 连接到一起，以定义丰富语义来计算表达式。

对于 #getValue、#getType、#setValue 和 #isReadOnly 方法，ELResolver 不负责解析所有可能的 (base, property) 对。实际上，大部分解析器将仅能处理一种类型的 base。要指示解析器成功地解析特定 (base, property) 对，它必须将 ELContext 的 propertyResolved 属性设置为 true。如果它无法处理给定对，则必须保持此属性不变。如果 propertyResolved 为 false，则调用者必须忽略该方法的返回值。

设计 #getFeatureDescriptors 和 #getCommonPropertyType 方法的主要目的是支持设计时工具，但它们也必须在运行时处理调用。可以使用 java.beans.Beans#isDesignTime 方法确定是否在设计时（或运行时）参考了解析器。

Enables customization of variable and property resolution behavior for EL expression evaluation.

While evaluating an expression, the ELResolver associated with the ELContext is consulted to do the initial resolution of the first variable of an expression. It is also consulted when a . or [] operator is encountered, except for the last such operator in a method expression, in which case the resultion rules are hard coded.

For example, in the EL expression ${employee.lastName}, the ELResolver determines what object employee refers to, and what it means to get the lastName property on that object.

Most methods in this class accept a base and property parameter. In the case of variable resolution (e.g. determining what employee refers to in ${employee.lastName}), the base parameter will be null and the property parameter will always be of type String. In this case, if the property is not a String, the behavior of the ELResolver is undefined.

In the case of property resolution, the base parameter identifies the base object and the property object identifies the property on that base. For example, in the expression ${employee.lastName}, base is the result of the variable resolution for employee and property is the string "lastName". In the expression ${y[x]}, base is the result of the variable resolution for y and property is the result of the variable resolution for x.

Though only a single ELResolver is associated with an ELContext, there are usually multiple resolvers considered for any given variable or property resolution. ELResolvers are combined together using CompositeELResolvers, to define rich semantics for evaluating an expression.

For the getValue(javax.el.ELContext, java.lang.Object, java.lang.Object), getType(javax.el.ELContext, java.lang.Object, java.lang.Object), setValue(javax.el.ELContext, java.lang.Object, java.lang.Object, java.lang.Object) and isReadOnly(javax.el.ELContext, java.lang.Object, java.lang.Object) methods, an ELResolver is not responsible for resolving all possible (base, property) pairs. In fact, most resolvers will only handle a base of a single type. To indicate that a resolver has successfully resolved a particular (base, property) pair, it must set the propertyResolved property of the ELContext to true. If it could not handle the given pair, it must leave this property alone. The caller must ignore the return value of the method if propertyResolved is false.

The getFeatureDescriptors(javax.el.ELContext, java.lang.Object) and getCommonPropertyType(javax.el.ELContext, java.lang.Object) methods are primarily designed for design-time tool support, but must handle invocation at runtime as well. The Beans.isDesignTime() method can be used to determine if the resolver is being consulted at design-time or runtime.

Since:

JSP 2.1

See Also:

CompositeELResolver, ELContext.getELResolver()

英文文档：

TYPE

public static final String TYPE

The attribute name of the named attribute in the FeatureDescriptor that specifies the runtime type of the variable or property.

See Also:

Constant Field Values

英文文档：

RESOLVABLE_AT_DESIGN_TIME

public static final String RESOLVABLE_AT_DESIGN_TIME

The attribute name of the named attribute in the FeatureDescriptor that specifies whether the variable or property can be resolved at runtime.

See Also:

Constant Field Values

public ELResolver()

英文文档：

ELResolver

public ELResolver()

abstract public Object getValue(ELContext context, Object base, Object property)
尝试在给定的 base 对象上解析给定的 property 对象。

如果此解析器处理给定的 (base, property) 对，则在返回前，ELContext 对象的 propertyResolved 属性必须设置为 true。如果调用此方法后此属性不为 true，则调用者应该忽略返回值。

context	此计算的上下文。
base	将返回属性值的 base 对象；或者为 null，表示解析顶级变量。
property	要解析的属性或变量。
return	如果 ELContext 的 propertyResolved 属性设置为 true，则返回变量或属性解析的结果；其他情况未定义。
Throws	NullPointerException: 如果 context 为 null
Throws	PropertyNotFoundException: 如果此 ELResolver 处理了给定的 (base, property) 对，但指定变量或属性不存在或不可读。
Throws	ELException: 如果执行属性或变量解析时抛出异常。抛出的异常必须作为此异常的 cause 属性包含（如果可用）。

英文文档：

getValue

public abstract Object getValue(ELContext context,
                                Object base,
                                Object property)

Attempts to resolve the given property object on the given base object.

If this resolver handles the given (base, property) pair, the propertyResolved property of the ELContext object must be set to true by the resolver, before returning. If this property is not true after this method is called, the caller should ignore the return value.

Parameters:

context - The context of this evaluation.

base - The base object whose property value is to be returned, or null to resolve a top-level variable.

property - The property or variable to be resolved.

Returns:

If the propertyResolved property of ELContext was set to true, then the result of the variable or property resolution; otherwise undefined.

Throws:

NullPointerException - if context is null

PropertyNotFoundException - if the given (base, property) pair is handled by this ELResolver but the specified variable or property does not exist or is not readable.

ELException - if an exception was thrown while performing the property or variable resolution. The thrown exception must be included as the cause property of this exception, if available.

abstract public Class<T> getType(ELContext context, Object base, Object property)
对于给定的 base 和 property，尝试标识最一般的对象类型，该类型对于将来调用 #setValue 方法时作为 value 参数传递的对象而言是可接受的。

如果此解析器处理给定的 (base, property) 对，则在返回前，ELContext 对象的 propertyResolved 属性必须设置为 true。如果调用此方法后此属性不为 true，则调用者应该忽略返回值。

这并非总是与 getValue().getClass() 相同。例如，如果是 ArrayELResolver，则 getType 方法将返回数组的元素类型，它可能是当前指定数组元素中的实际元素类型的超类。

context	此计算的上下文。
base	将分析属性值的 base 对象；或者为 null，表示分析顶级变量。
property	要返回可接受类型的属性或变量。
return	如果 ELContext 的 propertyResolved 属性设置为 true，则返回最一般的可接受类型；其他情况未定义。
Throws	NullPointerException: 如果 context 为 null
Throws	PropertyNotFoundException: 如果此 ELResolver 处理了给定的 (base, property) 对，但指定变量或属性不存在或不可读。
Throws	ELException: 如果执行属性或变量解析时抛出异常。抛出的异常必须作为此异常的 cause 属性包含（如果可用）。

英文文档：

getType

public abstract Class<?> getType(ELContext context,
                                 Object base,
                                 Object property)

For a given base and property, attempts to identify the most general type that is acceptable for an object to be passed as the value parameter in a future call to the setValue(javax.el.ELContext, java.lang.Object, java.lang.Object, java.lang.Object) method.

If this resolver handles the given (base, property) pair, the propertyResolved property of the ELContext object must be set to true by the resolver, before returning. If this property is not true after this method is called, the caller should ignore the return value.

This is not always the same as getValue().getClass(). For example, in the case of an ArrayELResolver, the getType method will return the element type of the array, which might be a superclass of the type of the actual element that is currently in the specified array element.

Parameters:

context - The context of this evaluation.

base - The base object whose property value is to be analyzed, or null to analyze a top-level variable.

property - The property or variable to return the acceptable type for.

Returns:

If the propertyResolved property of ELContext was set to true, then the most general acceptable type; otherwise undefined.

Throws:

NullPointerException - if context is null

PropertyNotFoundException - if the given (base, property) pair is handled by this ELResolver but the specified variable or property does not exist or is not readable.

ELException - if an exception was thrown while performing the property or variable resolution. The thrown exception must be included as the cause property of this exception, if available.

abstract public void setValue(ELContext context, Object base, Object property, Object value)
尝试在给定的 base 对象上设置给定的 property 对象的值。

如果此解析器处理给定的 (base, property) 对，则在返回前，ELContext 对象的 propertyResolved 属性必须设置为 true。如果调用此方法后此属性不为 true，则调用者可以放心地假定没有设置任何值。

context	此计算的上下文。
base	将设置属性值的 base 对象；或者为 null，表示设置顶级变量。
property	要设置的属性或变量。
value	用于设置属性或变量的值。
Throws	NullPointerException: 如果 context 为 null
Throws	PropertyNotFoundException: 如果此 ELResolver 处理了给定的 (base, property) 对，但指定变量或属性不存在。
Throws	PropertyNotWritableException: 如果此 ELResolver 处理了给定的 (base, property) 对，但指定的变量或属性不可写。
Throws	ELException: 如果尝试设置属性或变量时抛出异常。抛出的异常必须作为此异常的 cause 属性包含（如果可用）。

英文文档：

setValue

public abstract void setValue(ELContext context,
                              Object base,
                              Object property,
                              Object value)

Attempts to set the value of the given property object on the given base object.

If this resolver handles the given (base, property) pair, the propertyResolved property of the ELContext object must be set to true by the resolver, before returning. If this property is not true after this method is called, the caller can safely assume no value has been set.

Parameters:

context - The context of this evaluation.

base - The base object whose property value is to be set, or null to set a top-level variable.

property - The property or variable to be set.

value - The value to set the property or variable to.

Throws:

NullPointerException - if context is null

PropertyNotFoundException - if the given (base, property) pair is handled by this ELResolver but the specified variable or property does not exist.

PropertyNotWritableException - if the given (base, property) pair is handled by this ELResolver but the specified variable or property is not writable.

ELException - if an exception was thrown while attempting to set the property or variable. The thrown exception must be included as the cause property of this exception, if available.

abstract public boolean isReadOnly(ELContext context, Object base, Object property)
对于给定的 base 和 property，尝试确定调用 #setValue 是否将总是失败。

如果此解析器处理给定的 (base, property) 对，则在返回前，ELContext 对象的 propertyResolved 属性必须设置为 true。如果调用此方法后此属性不为 true，则调用者应该忽略返回值。

context	此计算的上下文。
base	将分析属性值的 base 对象；或者为 null，表示分析顶级变量。
property	要返回只读状态的属性或变量。
return	如果 ELContext 的 propertyResolved 属性被设置为 true，则在属性为只读的情况下返回 true，在非只读的情况下返回 false；其他情况未定义。
Throws	NullPointerException: 如果 context 为 null
Throws	PropertyNotFoundException: 如果此 ELResolver 处理了给定的 (base, property) 对，但指定变量或属性不存在。
Throws	ELException: 如果执行属性或变量解析时抛出异常。抛出的异常必须作为此异常的 cause 属性包含（如果可用）。

英文文档：

isReadOnly

public abstract boolean isReadOnly(ELContext context,
                                   Object base,
                                   Object property)

For a given base and property, attempts to determine whether a call to setValue(javax.el.ELContext, java.lang.Object, java.lang.Object, java.lang.Object) will always fail.

If this resolver handles the given (base, property) pair, the propertyResolved property of the ELContext object must be set to true by the resolver, before returning. If this property is not true after this method is called, the caller should ignore the return value.

Parameters:

context - The context of this evaluation.

base - The base object whose property value is to be analyzed, or null to analyze a top-level variable.

property - The property or variable to return the read-only status for.

Returns:

If the propertyResolved property of ELContext was set to true, then true if the property is read-only or false if not; otherwise undefined.

Throws:

NullPointerException - if context is null

PropertyNotFoundException - if the given (base, property) pair is handled by this ELResolver but the specified variable or property does not exist.

ELException - if an exception was thrown while performing the property or variable resolution. The thrown exception must be included as the cause property of this exception, if available.

abstract public java.util.Iterator<E> getFeatureDescriptors(ELContext context, Object base)
返回可以针对给定 base 对象进行解析的变量或属性集的有关信息。此方法可以用于自动完成的辅助工具。

如果 base 参数为 null，则解析器必须枚举它可以解析的顶级变量列表。

返回的 Iterator 必须包含 0 个或多个 java.beans.FeatureDescriptor 实例（无固定顺序）。如果是基本类型（如 int），则必须返回值 null。这样可以防止对所有可能的原始值进行无用迭代。返回值为 null 表示此解析器没有处理给定的 base 对象，或者结果太复杂而无法用此方法表示，此时应该使用 #getCommonPropertyType 方法。

每个 FeatureDescriptor 将包含有关单个变量或属性的信息。除了标准属性之外，FeatureDescriptor 必须拥有两个指定属性（通过 setValue 方法设置）：

• #TYPE - 此指定属性的值必须是 java.lang.Class 的实例，并且必须指定变量或属性的运行时类型。
• #RESOLVABLE_AT_DESIGN_TIME - 此指定属性的值必须是 java.lang.Boolean 的实例，并且必须指出在设计时尝试解析此属性是否安全。例如，如果 ELResolver 需要访问仅在运行时可用的资源并且没有提供可接受的模拟值，则尝试在设计时解析是不安全的。

调用者应该注意到返回的 Iterator 可能迭代非常大甚至无限大的属性集。调用者应该注意不要陷入无限循环。

这是一个最佳列表。并非所有 ELResolver 都将返回完全精确的结果，但它们都必须可以在设计时和运行时调用（即无论 Beans.isDesignTime() 是否返回 true）且不会引起错误。

ELContext 的 propertyResolved 属性与此方法无关。如果是复合解析器，则所有 ELResolver 的结果将串联在一起。

context	此计算的上下文。
base	要枚举有效属性集合的 base 对象；或者为 null，表示枚举此解析器可以计算的顶级变量集合。
return	包含 0 个或多个（可能无限多个）FeatureDescriptor 对象的 Iterator；如果此解析器不处理给定的 base 对象，或者结果太复杂而无法用此方法表示，则返回 null
See also	java.beans.FeatureDescriptor

英文文档：

getFeatureDescriptors

public abstract Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context,
                                                                  Object base)

Returns information about the set of variables or properties that can be resolved for the given base object. One use for this method is to assist tools in auto-completion.

If the base parameter is null, the resolver must enumerate the list of top-level variables it can resolve.

The Iterator returned must contain zero or more instances of FeatureDescriptor, in no guaranteed order. In the case of primitive types such as int, the value null must be returned. This is to prevent the useless iteration through all possible primitive values. A return value of null indicates that this resolver does not handle the given base object or that the results are too complex to represent with this method and the getCommonPropertyType(javax.el.ELContext, java.lang.Object) method should be used instead.

Each FeatureDescriptor will contain information about a single variable or property. In addition to the standard properties, the FeatureDescriptor must have two named attributes (as set by the setValue method):

• TYPE - The value of this named attribute must be an instance of java.lang.Class and specify the runtime type of the variable or property.
• RESOLVABLE_AT_DESIGN_TIME - The value of this named attribute must be an instance of java.lang.Boolean and indicates whether it is safe to attempt to resolve this property at design-time. For instance, it may be unsafe to attempt a resolution at design time if the ELResolver needs access to a resource that is only available at runtime and no acceptable simulated value can be provided.

The caller should be aware that the Iterator returned might iterate through a very large or even infinitely large set of properties. Care should be taken by the caller to not get stuck in an infinite loop.

This is a "best-effort" list. Not all ELResolvers will return completely accurate results, but all must be callable at both design-time and runtime (i.e. whether or not Beans.isDesignTime() returns true), without causing errors.

The propertyResolved property of the ELContext is not relevant to this method. The results of all ELResolvers are concatenated in the case of composite resolvers.

Parameters:

context - The context of this evaluation.

base - The base object whose set of valid properties is to be enumerated, or null to enumerate the set of top-level variables that this resolver can evaluate.

Returns:

An Iterator containing zero or more (possibly infinitely more) FeatureDescriptor objects, or null if this resolver does not handle the given base object or that the results are too complex to represent with this method

See Also:

FeatureDescriptor

abstract public Class<T> getCommonPropertyType(ELContext context, Object base)
在给定 base 对象的情况下，返回对于 property 参数此解析器可以接受的最一般类型。此方法可以用于自动完成的辅助工具。

此自动完成辅助工具还提供一种表示解析器接受原始值（如数组中的整数索引）的方式。例如，ArrayELResolver 将接受任何 int 作为 property，因此返回值将为 Integer.class。

context	此计算的上下文。
base	要返回最一般属性类型的 base 对象；或者为 null，表示枚举此解析器可以计算的顶级变量集合。
return	如果此 ELResolver 不了解如何处理给定的 base 对象，则返回 null；否则，如果接受任何 property 类型，则返回 Object.class；其他情况下，返回给定 base 可接受的最一般的 property 类型。

英文文档：

getCommonPropertyType

public abstract Class<?> getCommonPropertyType(ELContext context,
                                               Object base)

Returns the most general type that this resolver accepts for the property argument, given a base object. One use for this method is to assist tools in auto-completion.

This assists tools in auto-completion and also provides a way to express that the resolver accepts a primitive value, such as an integer index into an array. For example, the ArrayELResolver will accept any int as a property, so the return value would be Integer.class.

Parameters:

context - The context of this evaluation.

base - The base object to return the most general property type for, or null to enumerate the set of top-level variables that this resolver can evaluate.

Returns:

null if this ELResolver does not know how to handle the given base object; otherwise Object.class if any type of property is accepted; otherwise the most general property type accepted for the given base.

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