1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package org.apache.struts2.spi;
22
23 /***
24 * A central fixture of the Struts framework, the {@code ValueStack} is a stack which contains the actions
25 * which have executed in addition to other objects. Users can get and set values on the stack using expressions. The
26 * {@code ValueStack} will search down the stack starting with the most recent objects until it finds an object to
27 * which the expression can apply.
28 *
29 * @author crazybob@google.com (Bob Lee)
30 */
31 public interface ValueStack extends Iterable<Object> {
32
33 /***
34 * Gets the top, most recent object from the stack without changing the stack.
35 *
36 * @return the top object
37 */
38 Object peek();
39
40 /***
41 * Removes the top, most recent object from the stack.
42 *
43 * @return the top object
44 */
45 Object pop();
46
47 /***
48 * Pushes an object onto the stack.
49 *
50 * @param o
51 */
52 void push(Object o);
53
54 /***
55 * Creates a shallow copy of this stack.
56 *
57 * @return a new stack which contains the same objects as this one
58 */
59 ValueStack clone();
60
61 /***
62 * Queries the stack. Starts with the top, most recent object. If the expression can apply to the object, this
63 * method returns the result of evaluating the expression. If the expression does not apply, this method moves
64 * down the stack to the next object and repeats. Returns {@code null} if the expression doesn't apply to any
65 * objects.
66 *
67 * @param expression
68 * @return the evaluation of the expression against the first applicable object in the stack
69 */
70 Object get(String expression);
71
72 /***
73 * Queries the stack and converts the result to the specified type. Starts with the top, most recent object. If
74 * the expression can apply to the object, this method returns the result of evaluating the expression converted
75 * to the specified type. If the expression does not apply, this method moves down the stack to the next object
76 * and repeats. Returns {@code null} if the expression doesn't apply to any objects.
77 *
78 * @param expression
79 * @param asType the type to convert the result to
80 * @return the evaluation of the expression against the first applicable object in the stack converted to the
81 * specified type
82 */
83 <T> T get(String expression, Class<T> asType);
84
85 /***
86 * Queries the stack and converts the result to a {@code String}. Starts with the top, most recent object. If the
87 * expression can apply to the object, this method returns the result of evaluating the expression converted to a
88 * {@code String}. If the expression does not apply, this method moves down the stack to the next object and
89 * repeats. Returns {@code null} if the expression doesn't apply to any objects.
90 *
91 * @param expression
92 * @return the evaluation of the expression against the first applicable object in the stack converted to a {@code
93 * String}
94 */
95 String getString(String expression);
96
97 /***
98 * Sets a value on an object from the stack. This method starts at the top, most recent object. If the expression
99 * applies to that object, this methods sets the given value on that object using the expression and converting
100 * the type as necessary. If the expression does not apply, this method moves to the next object and repeats.
101 *
102 * @param expression
103 * @param value
104 */
105 void set(String expression, Object value);
106
107 /***
108 * Returns the number of object on the stack.
109 *
110 * @return size of stack
111 */
112 int size();
113 }