KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > components > flow > Interpreter


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation.
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.apache.cocoon.components.flow;
17
18 import org.apache.cocoon.environment.Redirector;
19
20 import java.util.List JavaDoc;
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  * &lt;map:call function="..." language="..."/&gt;
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 106089 2004-11-21 13:26:02Z lgawron $
77  */
78 public interface Interpreter {
79
80     public static class Argument {
81         public String JavaDoc name;
82         public String JavaDoc value;
83
84         public Argument(String JavaDoc name, String JavaDoc value) {
85             this.name = name;
86             this.value = value;
87         }
88
89         public String JavaDoc toString() {
90             return name + ": " + value;
91         }
92     }
93
94     public static final String JavaDoc ROLE = Interpreter.class.getName();
95
96     /**
97      * @return the unique ID for this interpreter.
98      */
99     String JavaDoc getInterpreterID();
100     
101     /**
102      * Set the unique ID for this interpreter.
103      */
104     void setInterpreterID(String JavaDoc interpreterID);
105
106     /**
107      * This method is called from the sitemap, using the syntax
108      *
109      * <pre>
110      * &lt;map:call function="..."/&gt;
111      * </pre>
112      *
113      * The method will execute the named function, which must be defined
114      * in the given language. There is no assumption made on how various
115      * arguments are passed to the function.
116      *
117      * <p>The <code>params</code> argument is a <code>List</code> object
118      * that contains <code>Interpreter.Argument</code> instances,
119      * representing the parameters to be passed to the called
120      * function. An <code>Argument</code> instance is a key-value pair,
121      * where the key is the name of the parameter, and the value is its
122      * desired value. Most languages will ignore the name value and
123      * simply pass to the function, in a positional order, the values of
124      * the argument. Some languages however can pass the arguments in a
125      * different order than the original prototype of the function. For
126      * these languages the ability to associate the actual argument with
127      * a formal parameter using its name is essential.
128      *
129      * <p>A particular language implementation may decide to put the
130      * environment, request, response etc. objects in the dynamic scope
131      * available to the function at the time of the call. Other
132      * implementations may decide to pass these as arguments to the
133      * called function.
134      *
135      * <p>The current implementation assumes the sitemap implementation
136      * is TreeProcessor.
137      *
138      * @param funName a <code>String</code> value, the name of the
139      * function to call
140      * @param params a <code>List</code> object whose components are
141      * CallFunctionNode.Argument instances. The interpretation of the
142      * parameters is left to the actual implementation of the
143      * interpreter.
144      * @param redirector a <code>Redirector</code> used to call views
145      */
146     void callFunction(String JavaDoc funName, List JavaDoc params, Redirector redirector)
147     throws Exception JavaDoc;
148
149     /**
150      * Forward the request to a Cocoon pipeline.
151      *
152      * @param uri a <code>String</code>, the URI of the forwarded request
153      * @param bizData an <code>Object</code>, the business data object
154      * to be made available to the forwarded pipeline
155      * @param continuation a <code>WebContinuation</code>, the
156      * continuation to be called to resume the processing
157      * @param redirector a <code>Redirector</code> used to call views
158      * @exception Exception if an error occurs
159      */
160     void forwardTo(String JavaDoc uri, Object JavaDoc bizData, WebContinuation continuation,
161                    Redirector redirector)
162     throws Exception JavaDoc;
163
164     /**
165      * Continues a previously started processing. The continuation
166      * object where the processing should start from is indicated by the
167      * <code>continuationId</code> string.
168      *
169      * @param continuationId a <code>String</code> value
170      *
171      * @param params a <code>List</code> value, containing the
172      * parameters to be passed when invoking the continuation. As
173      * opposed to the parameters passed by <code>callFunction</code>,
174      * these parameters will only become available in the language's
175      * environment, if at all.
176      *
177      * @param redirector a <code>Redirector</code> used to call views
178      * @exception Exception if an error occurs
179      */
180     void handleContinuation(String JavaDoc continuationId, List JavaDoc params,
181                             Redirector redirector)
182     throws Exception JavaDoc;
183 }
184
Popular Tags