View Javadoc

1   /*
2    * $Id: ValueStack.java 502296 2007-02-01 17:33:39Z niallp $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
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 }