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