Action


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.springframework.webflow.execution;
17  
18  /**
19   * A command that executes a behavior and returns a logical execution result a
20   * calling flow execution can respond to.
21   * <p>
22   * Actions typically delegate down to the application (or service) layer to
23   * perform business operations. They often retrieve data to support response
24   * rendering. They act as a bridge between a SWF web-tier and your middle-tier
25   * business logic layer.
26   * <p>
27   * When an action completes execution it signals a result event describing the
28   * outcome of that execution (for example, "success", "error", "yes", "no",
29   * "tryAgain", etc). In addition to providing a logical outcome the flow can
30   * respond to, a result event may have payload associated with it, for example a
31   * "success" return value or an "error" error code. The result event is
32   * typically used as grounds for a state transition out of the current state of
33   * the calling Flow.
34   * <p>
35   * Action implementations are often application-scoped singletons instantiated
36   * and managed by a web-tier Spring application context to take advantage of
37   * Spring's externalized configuration and dependency injection capabilities
38   * (which is a form of Inversion of Control [IoC]). Actions may also be stateful
39   * prototypes, storing conversational state as instance variables. Action
40   * instance definitions may also be locally scoped to a specific flow definition
41   * (see use of the "import" element of the root XML flow definition element.)
42   * <p>
43   * Note: Actions are directly instantiatable for use in a standalone test
44   * environment and can be parameterized with mocks or stubs, as they are simple
45   * POJOs. Action proxies may also be generated at runtime for delegating to POJO
46   * business operations that have no dependency on the Spring Web Flow API.
47   * <p>
48   * Note: if an Action is a singleton managed in application scope, take care not
49   * to store and/or modify caller-specific state in a unsafe manner. The Action
50   * {@link #execute(RequestContext)} method runs in an independently executing
51   * thread on each invocation so make sure you deal only with local data or
52   * internal, thread-safe services.
53   * <p>
54   * Note: an Action is not a controller like a Spring MVC controller or a Struts
55   * action is a controller. Flow actions are <i>commands</i>. Such commands do
56   * not select views, they execute arbitrary behavioral logic and then return an
57   * logical execution result. The flow that invokes an Action is responsible for
58   * responding to the execution result to decide what to do next. In Spring Web
59   * Flow, the flow <i>is</i> the controller.
60   * 
61   * @author Keith Donald
62   * @author Erwin Vervaet
63   */
64  public interface Action {
65  
66      /**
67       * Execute this action. Action execution will occur in the context of a
68       * request associated with an active flow execution.
69       * <p>
70       * Action invocation is typically triggered in a production environment by a
71       * state within a flow carrying out the execution of a flow definition. The
72       * result of action execution, a logical outcome event, can be used as
73       * grounds for a transition out of the calling state.
74       * <p>
75       * Note: The {@link RequestContext} argument to this method provides access
76       * to data about the active flow execution in the context of the currently
77       * executing thread. Among other things, this allows this action to access
78       * {@link RequestContext#getRequestScope() data} set by other actions, as
79       * well as set its own attributes it wishes to expose in a given scope.
80       * <p>
81       * Some notes about actions and their usage of the attribute scope types:
82       * <ul>
83       * <li>Attributes set in
84       * {@link RequestContext#getRequestScope() request scope} exist for the life
85       * of the currently executing request only.
86       * <li>Attributes set in {@link RequestContext#getFlashScope() flash scope}
87       * exist until the next external user event is signaled. That time includes
88       * the current request plus any redirect or additional refreshes to the next
89       * view.
90       * <li>Attributes set in {@link RequestContext#getFlowScope() flow scope}
91       * exist for the life of the flow session and will be
92       * cleaned up automatically when the flow session ends.
93       * <li>Attributes set in
94       * {@link RequestContext#getConversationScope() conversation scope} exist
95       * for the life of the entire flow execution representing a single logical
96       * "conversation" with a user.
97       * </ul>
98       * <p>
99       * All attributes present in any scope are typically exposed in a model
100      * for access by a view when an "interactive" state type such as a view
101      * state is entered.
102      * <p>
103      * Note: flow scope should generally not be used as a general purpose cache,
104      * but rather as a context for data needed locally by other states of the
105      * flow this action participates in. For example, it would be inappropriate
106      * to stuff large collections of objects (like those returned to support a
107      * search results view) into flow scope. Instead, put such result
108      * collections in request scope, and ensure you execute this action again
109      * each time you wish to view those results. 2nd level caches managed
110      * outside of SWF are more general cache solutions.
111      * <p>
112      * Note: as flow scoped attributes are eligible for serialization they
113      * should be <code>Serializable</code>.
114      * 
115      * @param context the action execution context, for accessing and setting
116      * data in a {@link ScopeType scope type}, as well as obtaining other flow
117      * contextual information (e.g. request context attributes and flow
118      * execution context information)
119      * @return a logical result outcome, used as grounds for a transition in the
120      * calling flow (e.g. "success", "error", "yes", "no", * ...)
121      * @throws Exception a exception occured during action execution, either
122      * checked or unchecked; note, any <i>recoverable</i> exceptions should be
123      * caught within this method and an appropriate result outcome returned
124      * <i>or</i> be handled by the current state of the calling flow execution.
125      */
126     public Event execute(RequestContext context) throws Exception  ;
127 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags