001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.components.flow;
018:
019: import org.apache.cocoon.environment.Redirector;
020:
021: import java.util.List;
022:
023: /**
024: * The interface to the flow scripting languages. This interface is
025: * for a component, which implements the appropriate language to be
026: * used for describing the flow. A system could have multiple
027: * components that implement this interface, each of them for a
028: * different scripting language.
029: *
030: * <p>A flow script defines what is the page flow in an interactive
031: * Web application. Usually the flow is defined in a high level
032: * programming language which provides the notion of continuations,
033: * which allows for the flow of the application to be described as a
034: * simple procedural program, without having to think about the
035: * application as a finite state machine which changes its internal
036: * state on each HTTP request from the client browser.
037: *
038: * <p>However an implementation may choose to use its own
039: * representation of an application, which may include XML
040: * representations of finite state machines. Note: this API has no
041: * provision for such implementations.
042: *
043: * <p>The component represented by this interface is called in three
044: * situations:
045: *
046: * <ul>
047: * <li>
048: * <p>From the sitemap, to invoke a top level function defined in a
049: * * given implementation language of the flow. This is done from
050: * the * sitemap using the construction:
051: *
052: * <pre>
053: * <map:call function="..." language="..."/>
054: * </pre>
055: *
056: * <p>The <code>language</code> attribute can be ignored if the *
057: * default language is used.
058: *
059: * <li>
060: * <p>From the sitemap, to continue a previously started
061: * computation. A previously started computation is saved in the
062: * form of a continuation inside the flow implementation language.
063: *
064: * <p>This case is similar with the above one, but the function
065: * invoked has a special name, specific to each language
066: * implementation. See the language implementation for more
067: * information on the function name and the arguments it receives.
068: *
069: * <li>
070: * <p>From a program in the flow layer. This is done to invoke a
071: * pipeline defined in the sitemap, to generate the response of the
072: * request.
073: * </ul>
074: *
075: * @author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>
076: * @since March 11, 2002
077: * @version CVS $Id: Interpreter.java 433543 2006-08-22 06:22:54Z crossley $
078: */
079: public interface Interpreter {
080:
081: public static class Argument {
082: public String name;
083: public String value;
084:
085: public Argument(String name, String value) {
086: this .name = name;
087: this .value = value;
088: }
089:
090: public String toString() {
091: return name + ": " + value;
092: }
093: }
094:
095: public static final String ROLE = Interpreter.class.getName();
096:
097: /**
098: * @return the unique ID for this interpreter.
099: */
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,
162: WebContinuation continuation, 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) throws Exception;
183: }
|