Renamed action-api to api to be consistent.

git-svn-id: https://svn.apache.org/repos/asf/struts/action2/trunk@418416 13f79535-47bb-0310-9956-ffa450edef68
2026-08-31 19:35:40 +00:00 · 2006-06-30 23:20:38 +00:00
parent 1e57331a5b
commit 2a24340dc5
18 changed files with 3 additions and 3 deletions
@@ -0,0 +1,45 @@
+package org.apache.struts2;
+
+/**
+ * Default action interface. Provided purely for user convenience. Struts does not require actions to implement any
+ * interfaces. Actions need only implement a public, no argument method which returns {@code String}. If a user does
+ * not specify a method name, Struts defaults to {@code execute()}.
+ *
+ * <p>For example:
+ *
+ * <pre>
+ *   static import ResultNames.*;
+ *
+ *   public class MyAction <b>implements Action</b> {
+ *
+ *     public String execute() {
+ *       return SUCCESS;
+ *     }
+ *   }
+ * </pre>
+ *
+ * <p>is equivalent to:
+ *
+ * <pre>
+ *   static import ResultNames.*;
+ *
+ *   public class MyAction {
+ *
+ *     public String execute() {
+ *       return SUCCESS;
+ *     }
+ *   }
+ * </pre>
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface Action {
+
+    /**
+     * Executes this action.
+     *
+     * @return result name which matches a result name from the action mapping in the configuration file. See {@link
+     *  ResultNames} for common suggestions.
+     */
+    String execute();
+}
@@ -0,0 +1,41 @@
+package org.apache.struts2;
+
+/**
+ * Implemented by actions which may need to record errors or messages.
+ *
+ * <pre>
+ *   static import ResultNames.*;
+ *
+ *   public class SetName implements MessageAware {
+ *
+ *     Messages messages;
+ *     String name;
+ *
+ *     public String execute() {
+ *       return SUCCESS;
+ *     }
+ *
+ *     public void setName(String name) {
+ *       if ("".equals(name))
+ *         messages.forField("name").addError("name.required");
+ *
+ *       this.name = name;
+ *     }
+ *
+ *     public void setMessages(Messages messages) {
+ *       this.messages = messages;
+ *     }
+ *   }
+ * </pre>
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface MessageAware {
+
+    /**
+     * Sets messages.
+     *
+     * @param messages messages
+     */
+    void setMessages(Messages messages);
+}
@@ -0,0 +1,194 @@
+package org.apache.struts2;
+
+import java.util.List;
+import java.util.Set;
+import java.util.Map;
+
+/**
+ * Collection of messages. Supports nesting messages by field name.
+ *
+ * <p>Uses keys when adding instead of actual messages to decouple code from messages.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface Messages {
+
+    /**
+     * Message severity.
+     */
+    public enum Severity {
+
+        /**
+         * Informational messages.
+         */
+        INFO,
+
+        /**
+         * Warning messages.
+         */
+        WARN,
+
+        /**
+         * Error messages.
+         */
+        ERROR,
+    }
+
+    /**
+     * Gets nested messages for the given field.
+     *
+     * <p>Supports dot notation to represent nesting. For example:
+     *
+     * <pre>
+     * messages.forField("foo").forField("bar") == messages.forField("foo.bar")
+     * </pre>
+     *
+     * @param fieldName name of the field
+     * @return nested {@code Messages} for given field name
+     */
+    Messages forField(String fieldName);
+
+    /**
+     * Gets map of field name to messages for that field.
+     *
+     * @return map of field name to {@code Messages}
+     */
+    Map<String, Messages> forFields();
+
+    /**
+     * Adds informational message.
+     *
+     * @param key message key
+     * @see Severity.INFO
+     */
+    void addInformation(String key);
+
+    /**
+     * Adds informational message.
+     *
+     * @param key message key
+     * @param arguments message arguments
+     * @see Severity.INFO
+     */
+    void addInformation(String key, Object... arguments);
+
+    /**
+     * Adds warning message.
+     *
+     * @param key message key
+     * @see Severity.WARN
+     */
+    void addWarning(String key);
+
+    /**
+     * Adds warning message.
+     *
+     * @param key message key
+     * @param arguments message arguments
+     * @see Severity.WARN
+     */
+    void addWarning(String key, Object... arguments);
+
+    /**
+     * Adds error message.
+     *
+     * @param key message key
+     * @see Severity.ERROR
+     */
+    void addError(String key);
+
+    /**
+     * Adds error message.
+     *
+     * @param key message key
+     * @param arguments message arguments
+     * @see Severity.ERROR
+     */
+    void addError(String key, Object... arguments);
+
+    /**
+     * Adds message.
+     *
+     * @param severity message severity
+     * @param key message key
+     */
+    void add(Severity severity, String key);
+
+    /**
+     * Adds request-scoped message.
+     *
+     * @param severity message severity
+     * @param key message key
+     * @param arguments message arguments
+     */
+    void add(Severity severity, String key, Object... arguments);
+
+    /**
+     * Gets set of severities for which this {@code Messages} instance has messages. Not recursive.
+     *
+     * @return unmodifiable set of {@link Severity} sorted from least to most severe
+     */
+    Set<Severity> getSeverities();
+
+    /**
+     * Gets message strings for the given severity. Not recursive.
+     *
+     * @param severity message severity
+     * @return unmodifiable list of messages
+     */
+    List<String> forSeverity(Severity severity);
+
+    /**
+     * Gets error message strings for this {@code Messages} instance. Not recursive.
+     *
+     * @return unmodifiable list of messages
+     */
+    List<String> getErrors();
+
+    /**
+     * Gets error message strings for this {@code Messages} instance. Not recursive.
+     *
+     * @return unmodifiable list of messages
+     */
+    List<String> getWarnings();
+
+    /**
+     * Gets informational message strings for this {@code Messages} instance. Not recursive.
+     *
+     * @return unmodifiable list of messages
+     */
+    List<String> getInformation();
+
+    /**
+     * Returns true if this or a nested {@code Messages} instance has error messages.
+     *
+     * @see Severity.ERROR
+     */
+    boolean hasErrors();
+
+    /**
+     * Returns true if this or a nested {@code Messages} instance has warning messages.
+     *
+     * @see Severity.WARN
+     */
+    boolean hasWarnings();
+
+    /**
+     * Returns true if this or a nested {@code Messages} instance has informational messages.
+     *
+     * @see Severity.INFO
+     */
+    boolean hasInformation();
+
+    /**
+     * Returns true if this and all nested {@code Messages} instances have no messages.
+     */
+    boolean isEmpty();
+
+    /**
+     * Returns true if this and all nested {@code Messages} instances have no messages for the given severity.
+     *
+     * @param severity message severity
+     */
+    boolean isEmpty(Severity severity);
+}
@@ -0,0 +1,36 @@
+package org.apache.struts2;
+
+/**
+ * Commonly used result names returned by action methods.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public final class ResultNames {
+
+    private ResultNames() {}
+
+    /**
+     * The action executed successfully.
+     */
+    public static final String SUCCESS = "success";
+
+    /**
+     * The action requires more input, i.e.&nbsp;a validation error occurred.
+     */
+    public static final String INPUT = "input";
+
+    /**
+     * The action requires the user to log in before executing.
+     */
+    public static final String LOGIN = "login";
+
+    /**
+     * The action execution failed irrecoverably.
+     */
+    public static final String ERROR = "error";
+
+    /**
+     * The action executed successfully, but do not execute a result.
+     */
+    public static final String NONE = "none";
+}
@@ -0,0 +1,17 @@
+package org.apache.struts2;
+
+import org.apache.struts2.MessageAware;
+
+/**
+ * Implemented by actions which wish to execute some validation logic before their action method. Useful for
+ * cross-field validations.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface Validatable extends MessageAware {
+
+    /**
+     * Validates input. Executes before action method.
+     */
+    public void validate();
+}
@@ -0,0 +1,18 @@
+package org.apache.struts2.servlet;
+
+import java.util.Map;
+
+/**
+ * Implemented by actions which need direct access to the request parameters.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface ParameterAware {
+
+    /**
+     * Sets parameters.
+     *
+     * @param parameters map of parameter name to parameter values
+     */
+    void setParameters(Map<String, String[]> parameters);
+}
@@ -0,0 +1,18 @@
+package org.apache.struts2.servlet;
+
+import javax.servlet.http.HttpServletRequest;
+
+/**
+ * Implemented by actions which need direct access to the servlet request.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface ServletRequestAware {
+
+    /**
+     * Sets the servlet request.
+     *
+     * @param request servlet request.
+     */
+    void setServletRequest(HttpServletRequest request);
+}
@@ -0,0 +1,18 @@
+package org.apache.struts2.servlet;
+
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * Implemented by actions which need direct access to the servlet response.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface ServletResponseAware {
+
+    /**
+     * Sets the servlet response.
+     *
+     * @param response servlet response
+     */
+    void setServletResponse(HttpServletResponse response);
+}
@@ -0,0 +1,59 @@
+package org.apache.struts2.spi;
+
+import java.lang.reflect.Method;
+
+/**
+ * Context of an action execution.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface ActionContext {
+
+    /**
+     * Gets action instance.
+     */
+    Object getAction();
+
+    /**
+     * Gets action method.
+     */
+    Method getMethod();
+
+    /**
+     * Gets action name.
+     */
+    String getActionName();
+
+    /**
+     * Gets the path for the action's namespace.
+     */
+    String getNamespacePath();
+
+    /**
+     * Gets the {@link Result} instance for the action.
+     *
+     * @return {@link Result} instance or {@code null} if we don't have a result yet.
+     */
+    Result getResult();
+
+    /**
+     * Adds a result interceptor for the action. Enables executing code before and after a result, executing an
+     * alternate result, etc.
+     */
+    void addResultInterceptor(Result interceptor);
+
+    /**
+     * Gets context of action which chained to us.
+     *
+     * @return context of previous action or {@code null} if this is the first action in the chain
+     */
+    ActionContext getPrevious();
+
+    /**
+     * Gets context of action which this action chained to.
+     *
+     * @return context of next action or {@code null} if we haven't chained to another action yet or this is the last
+     *  action in the chain.
+     */
+    ActionContext getNext();
+}
@@ -0,0 +1,16 @@
+package org.apache.struts2.spi;
+
+/**
+ * Intercepts an action request.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface Interceptor {
+
+    /**
+     * Intercepts an action request.
+     *
+     * @param requestContext current request context
+     */
+    String intercept(RequestContext requestContext) throws Exception;
+}
@@ -0,0 +1,107 @@
+package org.apache.struts2.spi;
+
+import org.apache.struts2.Messages;
+import org.apache.struts2.spi.ActionContext;
+
+import javax.servlet.ServletContext;
+import javax.servlet.http.Cookie;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * Request context. A single request may span multiple actions with action chaining.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface RequestContext {
+
+    /**
+     * Gets context of the currently executing action.
+     *
+     * @return current action context
+     */
+    ActionContext getActionContext();
+
+    /**
+     * Convenience method.&nbsp;Equivalent to {@code getActionContext().getAction()}.
+     *
+     * @return currently executing action
+     */
+    Object getAction();
+
+    /**
+     * Gets map of request parameters.
+     */
+    Map<String, String[]> getParameterMap();
+
+    /**
+     * Gets map of request attributes.
+     */
+    Map<String, Object> getAttributeMap();
+
+    /**
+     * Gets map of session attributes.
+     */
+    Map<String, Object> getSessionMap();
+
+    /**
+     * Gets map of application (servlet context) attributes.
+     */
+    Map<String, Object> getApplicationMap();
+
+    /**
+     * Finds cookies with the given name,
+     */
+    List<Cookie> findCookiesForName(String name);
+
+    /**
+     * Gets locale.
+     */
+    Locale getLocale();
+
+    /**
+     * Sets locale. Stores the locale in the session for future requests.
+     */
+    void setLocale(Locale locale);
+
+    /**
+     * Gets messages.
+     */
+    Messages getMessages();
+
+    /**
+     * Gets error messages.
+     */
+    Messages getErrors();
+
+    /**
+     * Gets the servlet request.
+     */
+    HttpServletRequest getServletRequest();
+
+    /**
+     * Gets the servlet response.
+     */
+    HttpServletResponse getServletResponse();
+
+    /**
+     * Gets the servlet context.
+     */
+    ServletContext getServletContext();
+
+    /**
+     * Gets the value stack.
+     */
+    ValueStack getValueStack();
+
+    /**
+     * Invokes the next interceptor or the action method if no more interceptors remain.
+     *
+     * @return result name
+     * @throws IllegalStateException if already invoked or called from the action
+     */
+    String proceed() throws Exception;
+}
@@ -0,0 +1,19 @@
+package org.apache.struts2.spi;
+
+import org.apache.struts2.spi.RequestContext;
+
+/**
+ * Implemented by actions that need access to the current {@link org.apache.struts2.spi.RequestContext}. Use
+ * judiciously.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface RequestContextAware {
+
+    /**
+     * Sets {@link org.apache.struts2.spi.RequestContext}.
+     *
+     * @param requestContext
+     */
+    void setRequestContext(RequestContext requestContext);
+}
@@ -0,0 +1,18 @@
+package org.apache.struts2.spi;
+
+import org.apache.struts2.spi.RequestContext;
+
+/**
+ * The result of an action request. Struts creates a new {@code Result} instance for each request.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public interface Result {
+
+    /**
+     * Executes result.
+     *
+     * @param requestContext
+     */
+    void execute(RequestContext requestContext) throws Exception;
+}
@@ -0,0 +1,56 @@
+package org.apache.struts2.spi;
+
+import org.apache.struts2.spi.RequestContext;
+
+import java.util.concurrent.Callable;
+
+/**
+ * Provides a reference to the current {@link org.apache.struts2.spi.RequestContext} for this thread.
+ *
+ * <p>Actions which spawn additional threads are responsible for setting this value if access to Struts from the
+ * additional thread is needed.
+ *
+ * @author crazybob@google.com (Bob Lee)
+ */
+public final class ThreadLocalRequestContext {
+
+    static ThreadLocal<RequestContext> threadLocalRequestContext = new ThreadLocal<RequestContext>();
+
+    private ThreadLocalRequestContext() {}
+
+    /**
+     * Sets {@link RequestContext} for the current thread and invokes the provided {@link Callable}. Restores previous
+     * {@code RequestContext} (if any) when finished.
+     *
+     * @param requestContext for current thread
+     * @param callable
+     * @return result of {@code callable}
+     * @throws Exception from {@code callable}
+     */
+    public static <T> T setAndCall(RequestContext requestContext, Callable<T> callable) throws Exception {
+        RequestContext old = threadLocalRequestContext.get();
+        try {
+            threadLocalRequestContext.set(requestContext);
+            return callable.call();
+        } finally {
+            if (old == null)
+                threadLocalRequestContext.remove();
+            else
+                threadLocalRequestContext.set(old);
+        }
+    }
+
+    /**
+     * Gets the {@link RequestContext} for the current thread.
+     *
+     * @return request for current thread
+     * @throws IllegalStateException if no request has been set
+     */
+    public static RequestContext get() {
+        RequestContext requestContext = threadLocalRequestContext.get();
+        if (requestContext == null) {
+            throw new IllegalStateException(ThreadLocalRequestContext.class.getName() + " has not been set.");
+        }
+        return requestContext;
+    }
+}
@@ -0,0 +1,93 @@
+package org.apache.struts2.spi;
+
+/**
+ * A central fixture of the Struts Action 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();
+}