View Javadoc

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  }