org.apache.cocoon.components.flow
Interface Interpreter


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:

Since:
March 11, 2002
Version:
$Id: Interpreter.html 1304280 2012-03-23 11:18:01Z ilgrosso $

Nested Class Summary
static class Interpreter.Argument
           
 
Field Summary
static String ROLE
           
 
Method Summary
 void callFunction(String funName, List params, org.apache.cocoon.environment.Redirector redirector)
          This method is called from the sitemap, using the syntax
 void forwardTo(String uri, Object bizData, WebContinuation continuation, org.apache.cocoon.environment.Redirector redirector)
          Forward the request to a Cocoon pipeline.
 String getInterpreterID()
           
 String getScriptExtension()
          Return the default extension of script files associated with this interpreter.
 void handleContinuation(String continuationId, List params, org.apache.cocoon.environment.Redirector redirector)
          Continues a previously started processing.
 void register(String source)
          Registers a source file with the interpreter.
 void setInterpreterID(String interpreterID)
          Set the unique ID for this interpreter.
 

Field Detail

ROLE

public static final String ROLE
Method Detail

getInterpreterID

public String getInterpreterID()
Returns:
the unique ID for this interpreter.

setInterpreterID

public void setInterpreterID(String interpreterID)
Set the unique ID for this interpreter.


callFunction

public void callFunction(String funName,
                         List params,
                         org.apache.cocoon.environment.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

public void forwardTo(String uri,
                      Object bizData,
                      WebContinuation continuation,
                      org.apache.cocoon.environment.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

public void handleContinuation(String continuationId,
                               List params,
                               org.apache.cocoon.environment.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

register

public void register(String source)
Registers a source file with the interpreter. Using this method an implementation keeps track of all the script files which are compiled. This allows them to reload the script files which get modified on the file system.


getScriptExtension

public String getScriptExtension()
Return the default extension of script files associated with this interpreter. The extension is used by the sitemap to automount all scripts from the "flow" directory. If this method returns null, no scripts are mounted automatically.

Returns:
The script extension, like ".js", or null.


Copyright 1999-2008 The Apache Software Foundation. All Rights Reserved.