1 /*
2 * Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.beans;
27
28 /**
29 * An <code>Expression</code> object represents a primitive expression
30 * in which a single method is applied to a target and a set of
31 * arguments to return a result - as in <code>"a.getFoo()"</code>.
32 * <p>
33 * In addition to the properties of the super class, the
34 * <code>Expression</code> object provides a <em>value</em> which
35 * is the object returned when this expression is evaluated.
36 * The return value is typically not provided by the caller and
37 * is instead computed by dynamically finding the method and invoking
38 * it when the first call to <code>getValue</code> is made.
39 *
40 * @see #getValue
41 * @see #setValue
42 *
43 * @since 1.4
44 *
45 * @author Philip Milne
46 */
47 public class Expression extends Statement {
48
49 private static Object unbound = new Object();
50
51 private Object value = unbound;
52
53 /**
54 * Creates a new <code>Statement</code> object with a <code>target</code>,
55 * <code>methodName</code> and <code>arguments</code> as per the parameters.
56 *
57 * @param target The target of this expression.
58 * @param methodName The methodName of this expression.
59 * @param arguments The arguments of this expression. If <code>null</code> then an empty array will be used.
60 *
61 * @see #getValue
62 */
63 @ConstructorProperties({"target", "methodName", "arguments"})
64 public Expression(Object target, String methodName, Object[] arguments) {
65 super(target, methodName, arguments);
66 }
67
68 /**
69 * Creates a new <code>Expression</code> object for a method
70 * that returns a result. The result will never be calculated
71 * however, since this constructor uses the <code>value</code>
72 * parameter to set the value property by calling the
73 * <code>setValue</code> method.
74 *
75 * @param value The value of this expression.
76 * @param target The target of this expression.
77 * @param methodName The methodName of this expression.
78 * @param arguments The arguments of this expression. If <code>null</code> then an empty array will be used.
79 *
80 * @see #setValue
81 */
82 public Expression(Object value, Object target, String methodName, Object[] arguments) {
83 this(target, methodName, arguments);
84 setValue(value);
85 }
86
87 /**
88 * If the value property of this instance is not already set,
89 * this method dynamically finds the method with the specified
90 * methodName on this target with these arguments and calls it.
91 * The result of the method invocation is first copied
92 * into the value property of this expression and then returned
93 * as the result of <code>getValue</code>. If the value property
94 * was already set, either by a call to <code>setValue</code>
95 * or a previous call to <code>getValue</code> then the value
96 * property is returned without either looking up or calling the method.
97 * <p>
98 * The value property of an <code>Expression</code> is set to
99 * a unique private (non-<code>null</code>) value by default and
100 * this value is used as an internal indication that the method
101 * has not yet been called. A return value of <code>null</code>
102 * replaces this default value in the same way that any other value
103 * would, ensuring that expressions are never evaluated more than once.
104 * <p>
105 * See the <code>excecute</code> method for details on how
106 * methods are chosen using the dynamic types of the target
107 * and arguments.
108 *
109 * @see Statement#execute
110 * @see #setValue
111 *
112 * @return The result of applying this method to these arguments.
113 */
114 public Object getValue() throws Exception {
115 if (value == unbound) {
116 setValue(invoke());
117 }
118 return value;
119 }
120
121 /**
122 * Sets the value of this expression to <code>value</code>.
123 * This value will be returned by the getValue method
124 * without calling the method associated with this
125 * expression.
126 *
127 * @param value The value of this expression.
128 *
129 * @see #getValue
130 */
131 public void setValue(Object value) {
132 this.value = value;
133 }
134
135 /*pp*/ String instanceName(Object instance) {
136 return instance == unbound ? "<unbound>" : super.instanceName(instance);
137 }
138
139 /**
140 * Prints the value of this expression using a Java-style syntax.
141 */
142 public String toString() {
143 return instanceName(value) + "=" + super.toString();
144 }
145 }
Save This Page