1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.struts.flow.core;
17
18 import java.util.List;
19
20 import org.apache.commons.chain.web.WebContext;
21
22 /***
23 * The interface to the flow scripting languages. This interface is
24 * for a component, which implements the appropriate language to be
25 * used for describing the flow. A system could have multiple
26 * components that implement this interface, each of them for a
27 * different scripting language.
28 *
29 * <p>A flow script defines what is the page flow in an interactive
30 * Web application. Usually the flow is defined in a high level
31 * programming language which provides the notion of continuations,
32 * which allows for the flow of the application to be described as a
33 * simple procedural program, without having to think about the
34 * application as a finite state machine which changes its internal
35 * state on each HTTP request from the client browser.
36 *
37 * <p>However an implementation may choose to use its own
38 * representation of an application, which may include XML
39 * representations of finite state machines. Note: this API has no
40 * provision for such implementations.
41 *
42 * <p>The component represented by this interface is called in three
43 * situations:
44 *
45 * <ul>
46 * <li>
47 * <p>From the sitemap, to invoke a top level function defined in a
48 * * given implementation language of the flow. This is done from
49 * the * sitemap using the construction:
50 *
51 * <pre>
52 * <map:call function="..." language="..."/>
53 * </pre>
54 *
55 * <p>The <code>language</code> attribute can be ignored if the *
56 * default language is used.
57 *
58 * <li>
59 * <p>From the sitemap, to continue a previously started
60 * computation. A previously started computation is saved in the
61 * form of a continuation inside the flow implementation language.
62 *
63 * <p>This case is similar with the above one, but the function
64 * invoked has a special name, specific to each language
65 * implementation. See the language implementation for more
66 * information on the function name and the arguments it receives.
67 *
68 * <li>
69 * <p>From a program in the flow layer. This is done to invoke a
70 * pipeline defined in the sitemap, to generate the response of the
71 * request.
72 * </ul>
73 *
74 * @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
75 * @since March 11, 2002
76 * @version CVS $Id: Interpreter.java 106091 2004-11-21 14:20:13Z lgawron $
77 */
78 public interface Interpreter {
79
80 public static class Argument {
81 public String name;
82 public String value;
83
84 public Argument(String name, String value) {
85 this.name = name;
86 this.value = value;
87 }
88
89 public String toString() {
90 return name + ": " + value;
91 }
92 }
93
94 /***
95 * @return the unique ID for this interpreter.
96 */
97 String getInterpreterID();
98
99 /***
100 * Set the unique ID for this interpreter.
101 */
102 void setInterpreterID(String interpreterID);
103
104 /***
105 * This method is called from the sitemap, using the syntax
106 *
107 * <pre>
108 * <map:call function="..."/>
109 * </pre>
110 *
111 * The method will execute the named function, which must be defined
112 * in the given language. There is no assumption made on how various
113 * arguments are passed to the function.
114 *
115 * <p>The <code>params</code> argument is a <code>List</code> object
116 * that contains <code>Interpreter.Argument</code> instances,
117 * representing the parameters to be passed to the called
118 * function. An <code>Argument</code> instance is a key-value pair,
119 * where the key is the name of the parameter, and the value is its
120 * desired value. Most languages will ignore the name value and
121 * simply pass to the function, in a positional order, the values of
122 * the argument. Some languages however can pass the arguments in a
123 * different order than the original prototype of the function. For
124 * these languages the ability to associate the actual argument with
125 * a formal parameter using its name is essential.
126 *
127 * <p>A particular language implementation may decide to put the
128 * environment, request, response etc. objects in the dynamic scope
129 * available to the function at the time of the call. Other
130 * implementations may decide to pass these as arguments to the
131 * called function.
132 *
133 * <p>The current implementation assumes the sitemap implementation
134 * is TreeProcessor.
135 *
136 * @param funName a <code>String</code> value, the name of the
137 * function to call
138 * @param params a <code>List</code> object whose components are
139 * CallFunctionNode.Argument instances. The interpretation of the
140 * parameters is left to the actual implementation of the
141 * interpreter.
142 * @param redirector a <code>Redirector</code> used to call views
143 */
144 Object callFunction(String funName, List params, WebContext chainCtx)
145 throws Exception;
146
147 /***
148 * Forward the request to a Cocoon pipeline.
149 *
150 * @param uri a <code>String</code>, the URI of the forwarded request
151 * @param bizData an <code>Object</code>, the business data object
152 * to be made available to the forwarded pipeline
153 * @param continuation a <code>WebContinuation</code>, the
154 * continuation to be called to resume the processing
155 * @param redirector a <code>Redirector</code> used to call views
156 * @exception Exception if an error occurs
157 */
158
159
160
161
162 /***
163 * Continues a previously started processing. The continuation
164 * object where the processing should start from is indicated by the
165 * <code>continuationId</code> string.
166 *
167 * @param continuationId a <code>String</code> value
168 *
169 * @param params a <code>List</code> value, containing the
170 * parameters to be passed when invoking the continuation. As
171 * opposed to the parameters passed by <code>callFunction</code>,
172 * these parameters will only become available in the language's
173 * environment, if at all.
174 *
175 * @param redirector a <code>Redirector</code> used to call views
176 * @exception Exception if an error occurs
177 */
178 void handleContinuation(String continuationId, List params,
179 WebContext chainCtx)
180 throws Exception;
181 }