/*
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.beans;
An Expression object represents a primitive expression in which a single method is applied to a target and a set of arguments to return a result - as in "a.getFoo()". In addition to the properties of the super class, the Expression object provides a value which is the object returned when this expression is evaluated. The return value is typically not provided by the caller and is instead computed by dynamically finding the method and invoking it when the first call to getValue is made.
Author: Philip Milne See Also: Since: 1.4
/**
* An {@code Expression} object represents a primitive expression
* in which a single method is applied to a target and a set of
* arguments to return a result - as in {@code "a.getFoo()"}.
* <p>
* In addition to the properties of the super class, the
* {@code Expression} object provides a <em>value</em> which
* is the object returned when this expression is evaluated.
* The return value is typically not provided by the caller and
* is instead computed by dynamically finding the method and invoking
* it when the first call to {@code getValue} is made.
*
* @see #getValue
* @see #setValue
*
* @since 1.4
*
* @author Philip Milne
*/
public class Expression extends Statement {
private static Object unbound = new Object();
private Object value = unbound;
Creates a new Expression object for the specified target object to invoke the method specified by the name and by the array of arguments. The target and the methodName values should not be null. Otherwise an attempt to execute this Expression will result in a NullPointerException. If the arguments value is null, an empty array is used as the value of the arguments property.
Params: - target – the target object of this expression
- methodName – the name of the method to invoke on the specified target
- arguments – the array of arguments to invoke the specified method
See Also:
/**
* Creates a new {@link Expression} object
* for the specified target object to invoke the method
* specified by the name and by the array of arguments.
* <p>
* The {@code target} and the {@code methodName} values should not be {@code null}.
* Otherwise an attempt to execute this {@code Expression}
* will result in a {@code NullPointerException}.
* If the {@code arguments} value is {@code null},
* an empty array is used as the value of the {@code arguments} property.
*
* @param target the target object of this expression
* @param methodName the name of the method to invoke on the specified target
* @param arguments the array of arguments to invoke the specified method
*
* @see #getValue
*/
@ConstructorProperties({"target", "methodName", "arguments"})
public Expression(Object target, String methodName, Object[] arguments) {
super(target, methodName, arguments);
}
Creates a new Expression object with the specified value for the specified target object to invoke the method specified by the name and by the array of arguments. The value value is used as the value of the value property, so the getValue method will return it without executing this Expression. The target and the methodName values should not be null. Otherwise an attempt to execute this Expression will result in a NullPointerException. If the arguments value is null, an empty array is used as the value of the arguments property.
Params: - value – the value of this expression
- target – the target object of this expression
- methodName – the name of the method to invoke on the specified target
- arguments – the array of arguments to invoke the specified method
See Also:
/**
* Creates a new {@link Expression} object with the specified value
* for the specified target object to invoke the method
* specified by the name and by the array of arguments.
* The {@code value} value is used as the value of the {@code value} property,
* so the {@link #getValue} method will return it
* without executing this {@code Expression}.
* <p>
* The {@code target} and the {@code methodName} values should not be {@code null}.
* Otherwise an attempt to execute this {@code Expression}
* will result in a {@code NullPointerException}.
* If the {@code arguments} value is {@code null},
* an empty array is used as the value of the {@code arguments} property.
*
* @param value the value of this expression
* @param target the target object of this expression
* @param methodName the name of the method to invoke on the specified target
* @param arguments the array of arguments to invoke the specified method
*
* @see #setValue
*/
public Expression(Object value, Object target, String methodName, Object[] arguments) {
this(target, methodName, arguments);
setValue(value);
}
{@inheritDoc}
If the invoked method completes normally, the value it returns is copied in the value property. Note that the value property is set to null, if the return type of the underlying method is void.
Throws: - NullPointerException – if the value of the
target or methodName property is null - NoSuchMethodException – if a matching method is not found
- SecurityException – if a security manager exists and
it denies the method invocation
- Exception – that is thrown by the invoked method
See Also: Since: 1.7
/**
* {@inheritDoc}
* <p>
* If the invoked method completes normally,
* the value it returns is copied in the {@code value} property.
* Note that the {@code value} property is set to {@code null},
* if the return type of the underlying method is {@code void}.
*
* @throws NullPointerException if the value of the {@code target} or
* {@code methodName} property is {@code null}
* @throws NoSuchMethodException if a matching method is not found
* @throws SecurityException if a security manager exists and
* it denies the method invocation
* @throws Exception that is thrown by the invoked method
*
* @see java.lang.reflect.Method
* @since 1.7
*/
@Override
public void execute() throws Exception {
setValue(invoke());
}
If the value property of this instance is not already set, this method dynamically finds the method with the specified methodName on this target with these arguments and calls it. The result of the method invocation is first copied into the value property of this expression and then returned as the result of getValue. If the value property was already set, either by a call to setValue or a previous call to getValue then the value property is returned without either looking up or calling the method. The value property of an Expression is set to a unique private (non-null) value by default and this value is used as an internal indication that the method has not yet been called. A return value of null replaces this default value in the same way that any other value would, ensuring that expressions are never evaluated more than once.
See the execute method for details on how methods are chosen using the dynamic types of the target and arguments.
Throws: - Exception – if the method with the specified methodName
throws an exception
See Also: Returns: The result of applying this method to these arguments.
/**
* If the value property of this instance is not already set,
* this method dynamically finds the method with the specified
* methodName on this target with these arguments and calls it.
* The result of the method invocation is first copied
* into the value property of this expression and then returned
* as the result of {@code getValue}. If the value property
* was already set, either by a call to {@code setValue}
* or a previous call to {@code getValue} then the value
* property is returned without either looking up or calling the method.
* <p>
* The value property of an {@code Expression} is set to
* a unique private (non-{@code null}) value by default and
* this value is used as an internal indication that the method
* has not yet been called. A return value of {@code null}
* replaces this default value in the same way that any other value
* would, ensuring that expressions are never evaluated more than once.
* <p>
* See the {@code execute} method for details on how
* methods are chosen using the dynamic types of the target
* and arguments.
*
* @see Statement#execute
* @see #setValue
*
* @return The result of applying this method to these arguments.
* @throws Exception if the method with the specified methodName
* throws an exception
*/
public Object getValue() throws Exception {
if (value == unbound) {
setValue(invoke());
}
return value;
}
Sets the value of this expression to value. This value will be returned by the getValue method without calling the method associated with this expression. Params: - value – The value of this expression.
See Also:
/**
* Sets the value of this expression to {@code value}.
* This value will be returned by the getValue method
* without calling the method associated with this
* expression.
*
* @param value The value of this expression.
*
* @see #getValue
*/
public void setValue(Object value) {
this.value = value;
}
/*pp*/ String instanceName(Object instance) {
return instance == unbound ? "<unbound>" : super.instanceName(instance);
}
Prints the value of this expression using a Java-style syntax.
/**
* Prints the value of this expression using a Java-style syntax.
*/
public String toString() {
return instanceName(value) + "=" + super.toString();
}
}