org.apache.cocoon.components.flow
Interface Interpreter

All Known Implementing Classes:

AbstractInterpreter, ApplesProcessor, CompilingInterpreter, FOM_JavaScriptInterpreter, JavaInterpreter

public interface Interpreter

The interface to the flow scripting languages. This interface is for a component, which implements the appropriate language to be used for describing the flow. A system could have multiple components that implement this interface, each of them for a different scripting language.

A flow script defines what is the page flow in an interactive Web application. Usually the flow is defined in a high level programming language which provides the notion of continuations, which allows for the flow of the application to be described as a simple procedural program, without having to think about the application as a finite state machine which changes its internal state on each HTTP request from the client browser.

However an implementation may choose to use its own representation of an application, which may include XML representations of finite state machines. Note: this API has no provision for such implementations.

The component represented by this interface is called in three situations:

• From the sitemap, to invoke a top level function defined in a * given implementation language of the flow. This is done from the * sitemap using the construction:

        <map:call function="..." language="..."/>
      

  The language attribute can be ignored if the * default language is used.

• From the sitemap, to continue a previously started computation. A previously started computation is saved in the form of a continuation inside the flow implementation language.

  This case is similar with the above one, but the function invoked has a special name, specific to each language implementation. See the language implementation for more information on the function name and the arguments it receives.

• From a program in the flow layer. This is done to invoke a pipeline defined in the sitemap, to generate the response of the request.

Since:

March 11, 2002

Version:

CVS $Id: Interpreter.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Ovidiu Predescu

Nested Class Summary

static class

Interpreter.Argument

Field Summary

static String

ROLE

Method Summary

void	callFunction(String funName, List params, Redirector redirector) This method is called from the sitemap, using the syntax <map:call function="..."
void	forwardTo(String uri, Object bizData, WebContinuation continuation, Redirector redirector) Forward the request to a Cocoon pipeline.
String	getInterpreterID()
void	handleContinuation(String continuationId, List params, Redirector redirector) Continues a previously started processing.
void	setInterpreterID(String interpreterID) Set the unique ID for this interpreter.

Field Detail

ROLE

static final String ROLE

Method Detail

getInterpreterID

String getInterpreterID()

Returns:

the unique ID for this interpreter.

setInterpreterID

void setInterpreterID(String interpreterID)

Set the unique ID for this interpreter.

callFunction

void callFunction(String funName,
                  List params,
                  Redirector redirector)
                  throws Exception

This method is called from the sitemap, using the syntax

   <map:call function="..."/>
 

The method will execute the named function, which must be defined in the given language. There is no assumption made on how various arguments are passed to the function.

The params argument is a List object that contains Interpreter.Argument instances, representing the parameters to be passed to the called function. An Argument instance is a key-value pair, where the key is the name of the parameter, and the value is its desired value. Most languages will ignore the name value and simply pass to the function, in a positional order, the values of the argument. Some languages however can pass the arguments in a different order than the original prototype of the function. For these languages the ability to associate the actual argument with a formal parameter using its name is essential.

A particular language implementation may decide to put the environment, request, response etc. objects in the dynamic scope available to the function at the time of the call. Other implementations may decide to pass these as arguments to the called function.

The current implementation assumes the sitemap implementation is TreeProcessor.

Parameters:

funName - a String value, the name of the function to call

params - a List object whose components are CallFunctionNode.Argument instances. The interpretation of the parameters is left to the actual implementation of the interpreter.

redirector - a Redirector used to call views

Throws:

Exception

forwardTo

void forwardTo(String uri,
               Object bizData,
               WebContinuation continuation,
               Redirector redirector)
               throws Exception

Forward the request to a Cocoon pipeline.

Parameters:

uri - a String, the URI of the forwarded request

bizData - an Object, the business data object to be made available to the forwarded pipeline

continuation - a WebContinuation, the continuation to be called to resume the processing

redirector - a Redirector used to call views

Throws:

Exception - if an error occurs

handleContinuation

void handleContinuation(String continuationId,
                        List params,
                        Redirector redirector)
                        throws Exception

Continues a previously started processing. The continuation object where the processing should start from is indicated by the continuationId string.

Parameters:

continuationId - a String value

params - a List value, containing the parameters to be passed when invoking the continuation. As opposed to the parameters passed by callFunction, these parameters will only become available in the language's environment, if at all.

redirector - a Redirector used to call views

Throws:

Exception - if an error occurs