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