| /* |
| * $Id$ |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| package org.apache.struts2.spi; |
| |
| /** |
| * A central fixture of the Struts framework, the {@code ValueStack} is a stack which contains the actions |
| * which have executed in addition to other objects. Users can get and set values on the stack using expressions. The |
| * {@code ValueStack} will search down the stack starting with the most recent objects until it finds an object to |
| * which the expression can apply. |
| * |
| * @author crazybob@google.com (Bob Lee) |
| */ |
| public interface ValueStack extends Iterable<Object> { |
| |
| /** |
| * Gets the top, most recent object from the stack without changing the stack. |
| * |
| * @return the top object |
| */ |
| Object peek(); |
| |
| /** |
| * Removes the top, most recent object from the stack. |
| * |
| * @return the top object |
| */ |
| Object pop(); |
| |
| /** |
| * Pushes an object onto the stack. |
| * |
| * @param o |
| */ |
| void push(Object o); |
| |
| /** |
| * Creates a shallow copy of this stack. |
| * |
| * @return a new stack which contains the same objects as this one |
| */ |
| ValueStack clone(); |
| |
| /** |
| * Queries the stack. Starts with the top, most recent object. If the expression can apply to the object, this |
| * method returns the result of evaluating the expression. If the expression does not apply, this method moves |
| * down the stack to the next object and repeats. Returns {@code null} if the expression doesn't apply to any |
| * objects. |
| * |
| * @param expression |
| * @return the evaluation of the expression against the first applicable object in the stack |
| */ |
| Object get(String expression); |
| |
| /** |
| * Queries the stack and converts the result to the specified type. Starts with the top, most recent object. If |
| * the expression can apply to the object, this method returns the result of evaluating the expression converted |
| * to the specified type. If the expression does not apply, this method moves down the stack to the next object |
| * and repeats. Returns {@code null} if the expression doesn't apply to any objects. |
| * |
| * @param expression |
| * @param asType the type to convert the result to |
| * @return the evaluation of the expression against the first applicable object in the stack converted to the |
| * specified type |
| */ |
| <T> T get(String expression, Class<T> asType); |
| |
| /** |
| * Queries the stack and converts the result to a {@code String}. Starts with the top, most recent object. If the |
| * expression can apply to the object, this method returns the result of evaluating the expression converted to a |
| * {@code String}. If the expression does not apply, this method moves down the stack to the next object and |
| * repeats. Returns {@code null} if the expression doesn't apply to any objects. |
| * |
| * @param expression |
| * @return the evaluation of the expression against the first applicable object in the stack converted to a {@code |
| * String} |
| */ |
| String getString(String expression); |
| |
| /** |
| * Sets a value on an object from the stack. This method starts at the top, most recent object. If the expression |
| * applies to that object, this methods sets the given value on that object using the expression and converting |
| * the type as necessary. If the expression does not apply, this method moves to the next object and repeats. |
| * |
| * @param expression |
| * @param value |
| */ |
| void set(String expression, Object value); |
| |
| /** |
| * Returns the number of object on the stack. |
| * |
| * @return size of stack |
| */ |
| int size(); |
| } |