org.zkoss.zel.impl.MethodExpressionImpl Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.zkoss.zel.impl;
import java.io.Externalizable;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import org.zkoss.zel.ELContext;
import org.zkoss.zel.ELException;
import org.zkoss.zel.FunctionMapper;
import org.zkoss.zel.MethodExpression;
import org.zkoss.zel.MethodInfo;
import org.zkoss.zel.MethodNotFoundException;
import org.zkoss.zel.PropertyNotFoundException;
import org.zkoss.zel.VariableMapper;
import org.zkoss.zel.impl.lang.EvaluationContext;
import org.zkoss.zel.impl.lang.ExpressionBuilder;
import org.zkoss.zel.impl.parser.Node;
import org.zkoss.zel.impl.util.ReflectionUtil;
/**
* An Expression that refers to a method on an object.
*
*
* The {@link org.zkoss.zel.ExpressionFactory#createMethodExpression} method
* can be used to parse an expression string and return a concrete instance
* of MethodExpression that encapsulates the parsed expression.
* The {@link FunctionMapper} is used at parse time, not evaluation time,
* so one is not needed to evaluate an expression using this class.
* However, the {@link ELContext} is needed at evaluation time.
*
* The {@link #getMethodInfo} and {@link #invoke} methods will evaluate the
* expression each time they are called. The {@link org.zkoss.zel.ELResolver} in the
* ELContext is used to resolve the top-level variables and to
* determine the behavior of the . and []
* operators. For any of the two methods, the
* {@link org.zkoss.zel.ELResolver#getValue} method is used to resolve all properties
* up to but excluding the last one. This provides the base object
* on which the method appears. If the base object is null, a
* NullPointerException must be thrown. At the last resolution,
* the final property is then coerced to a String,
* which provides the name of the method to be found. A method matching the
* name and expected parameters provided at parse time is found and it is
* either queried or invoked (depending on the method called on this
* MethodExpression).
*
* See the notes about comparison, serialization and immutability in
* the {@link org.zkoss.zel.Expression} javadocs.
*
* @see org.zkoss.zel.ELResolver
* @see org.zkoss.zel.Expression
* @see org.zkoss.zel.ExpressionFactory
* @see org.zkoss.zel.MethodExpression
*
* @author Jacob Hookom [[email protected]]
*/
public final class MethodExpressionImpl extends MethodExpression implements
Externalizable {
private Class expectedType;
private String expr;
private FunctionMapper fnMapper;
private VariableMapper varMapper;
private transient Node node;
private Class[] paramTypes;
public MethodExpressionImpl() {
super();
}
public MethodExpressionImpl(String expr, Node node,
FunctionMapper fnMapper, VariableMapper varMapper,
Class expectedType, Class[] paramTypes) {
super();
this.expr = expr;
this.node = node;
this.fnMapper = fnMapper;
this.varMapper = varMapper;
this.expectedType = expectedType;
this.paramTypes = paramTypes;
}
/**
* Determines whether the specified object is equal to this
* Expression.
*
*
* The result is true if and only if the argument is not
* null, is an Expression object that is the
* of the same type (ValueExpression or
* MethodExpression), and has an identical parsed
* representation.
*
*
*
* Note that two expressions can be equal if their expression Strings are
* different. For example, ${fn1:foo()} and
* ${fn2:foo()} are equal if their corresponding
* FunctionMappers mapped fn1:foo and
* fn2:foo to the same method.
*
*
* @param obj
* the Object to test for equality.
* @return true if obj equals this
* Expression; false otherwise.
* @see java.util.Hashtable
* @see java.lang.Object#equals(java.lang.Object)
*/
public boolean equals(Object obj) {
return (obj instanceof MethodExpressionImpl && obj.hashCode() == this
.hashCode());
}
/**
* Returns the original String used to create this Expression,
* unmodified.
*
*
* This is used for debugging purposes but also for the purposes of
* comparison (e.g. to ensure the expression in a configuration file has not
* changed).
*
*
*
* This method does not provide sufficient information to re-create an
* expression. Two different expressions can have exactly the same
* expression string but different function mappings. Serialization should
* be used to save and restore the state of an Expression.
*
*
* @return The original expression String.
*
* @see org.zkoss.zel.Expression#getExpressionString()
*/
public String getExpressionString() {
return this.expr;
}
/**
* Evaluates the expression relative to the provided context, and returns
* information about the actual referenced method.
*
* @param context
* The context of this evaluation
* @return an instance of MethodInfo containing information
* about the method the expression evaluated to.
* @throws NullPointerException
* if context is null or the base object is
* null on the last resolution.
* @throws PropertyNotFoundException
* if one of the property resolutions failed because a specified
* variable or property does not exist or is not readable.
* @throws MethodNotFoundException
* if no suitable method can be found.
* @throws ELException
* if an exception was thrown while performing property or
* variable resolution. The thrown exception must be included as
* the cause property of this exception, if available.
* @see org.zkoss.zel.MethodExpression#getMethodInfo(org.zkoss.zel.ELContext)
*/
public MethodInfo getMethodInfo(ELContext context)
throws PropertyNotFoundException, MethodNotFoundException,
ELException {
Node n = this.getNode();
EvaluationContext ctx = new EvaluationContext(context, this.fnMapper,
this.varMapper);
ctx.notifyBeforeEvaluation(getExpressionString());
MethodInfo result = n.getMethodInfo(ctx, this.paramTypes);
ctx.notifyAfterEvaluation(getExpressionString());
return result;
}
private Node getNode() throws ELException {
if (this.node == null) {
this.node = ExpressionBuilder.createNode(this.expr);
}
return this.node;
}
/**
* Returns the hash code for this Expression.
*
*
* See the note in the {@link #equals} method on how two expressions can be
* equal if their expression Strings are different. Recall that if two
* objects are equal according to the equals(Object) method,
* then calling the hashCode method on each of the two
* objects must produce the same integer result. Implementations must take
* special note and implement hashCode correctly.
*
*
* @return The hash code for this Expression.
* @see #equals
* @see java.util.Hashtable
* @see java.lang.Object#hashCode()
*/
public int hashCode() {
return this.expr.hashCode();
}
/**
* Evaluates the expression relative to the provided context, invokes the
* method that was found using the supplied parameters, and returns the
* result of the method invocation.
*
* @param context
* The context of this evaluation.
* @param params
* The parameters to pass to the method, or null
* if no parameters.
* @return the result of the method invocation (null if the
* method has a void return type).
* @throws NullPointerException
* if context is null or the base object is
* null on the last resolution.
* @throws PropertyNotFoundException
* if one of the property resolutions failed because a specified
* variable or property does not exist or is not readable.
* @throws MethodNotFoundException
* if no suitable method can be found.
* @throws ELException
* if an exception was thrown while performing property or
* variable resolution. The thrown exception must be included as
* the cause property of this exception, if available. If the
* exception thrown is an InvocationTargetException,
* extract its cause and pass it to the
* ELException constructor.
* @see org.zkoss.zel.MethodExpression#invoke(org.zkoss.zel.ELContext,
* java.lang.Object[])
*/
public Object invoke(ELContext context, Object[] params)
throws PropertyNotFoundException, MethodNotFoundException,
ELException {
EvaluationContext ctx = new EvaluationContext(context, this.fnMapper,
this.varMapper);
ctx.notifyBeforeEvaluation(getExpressionString());
Object result = this.getNode().invoke(ctx, this.paramTypes, params);
ctx.notifyAfterEvaluation(getExpressionString());
return result;
}
/*
* (non-Javadoc)
*
* @see java.io.Externalizable#readExternal(java.io.ObjectInput)
*/
public void readExternal(ObjectInput in) throws IOException,
ClassNotFoundException {
this.expr = in.readUTF();
String type = in.readUTF();
if (!"".equals(type)) {
this.expectedType = ReflectionUtil.forName(type);
}
this.paramTypes = ReflectionUtil.toTypeArray(((String[]) in
.readObject()));
this.fnMapper = (FunctionMapper) in.readObject();
this.varMapper = (VariableMapper) in.readObject();
}
/*
* (non-Javadoc)
*
* @see java.io.Externalizable#writeExternal(java.io.ObjectOutput)
*/
public void writeExternal(ObjectOutput out) throws IOException {
out.writeUTF(this.expr);
out.writeUTF((this.expectedType != null) ? this.expectedType.getName()
: "");
out.writeObject(ReflectionUtil.toTypeNameArray(this.paramTypes));
out.writeObject(this.fnMapper);
out.writeObject(this.varMapper);
}
public boolean isLiteralText() {
return false;
}
/**
* @since EL 3.0
*/
public boolean isParametersProvided() {
return this.getNode().isParametersProvided();
}
/**
* @since EL 2.2
* Note: The spelling mistake is deliberate.
* isParmetersProvided() - Specification definition
* isParametersProvided() - Corrected spelling
*/
public boolean isParmetersProvided() {
return this.getNode().isParametersProvided();
}
}