coliver 2003/03/05 19:44:49
Added: src/idl/cocoon cocoon.idl
src/idl/cocoon_flow cocoon_flow.idl
Log:
initial interface definitions
Revision Changes Path
1.1 xml-cocoon2/src/idl/cocoon/cocoon.idl
Index: cocoon.idl
===================================================================
module cocoon {
/**
* @see org.apache.cocoon.environment.Request
*/
interface Request {
};
interface Response {
};
interface Session {
};
interface Context_ {
};
interface Environment {
};
interface ComponentManager {
};
/**
* @see java.io.OutputStream
*/
interface OutputStream {
};
interface Function {
};
typedef sequence<string> StringArray;
const short COLUMNCOUNT = 1;
const short ROWCOUNT = 1;
typedef Object Rows[ROWCOUNT];
typedef Object RowsByIndex[ROWCOUNT][COLUMNCOUNT];
interface XForm;
typedef sequence<XForm> XForms;
};
1.1 xml-cocoon2/src/idl/cocoon_flow/cocoon_flow.idl
Index: cocoon_flow.idl
===================================================================
/**
* <p>The general flow of actions in an application which uses the control flow is
as described below.</p>
*
* <p>The request is received by Cocoon and passed to the sitemap for processing. In
the sitemap, you can do two things to pass the control to the Controller layer:</p>
*
* <p><ul></p>
*
* <p><li>you can invoke a JavaScript top-level function to start processing a
logically grouped sequences of pages. Each time a response page is being sent back to
the client browser from this function, the processing of the JavaScript code stops at
the point the page is sent back, and the HTTP request finishes. Through the magic of
continuations, the execution state is saved in a continuation object. Each
continuation is given a unique string id, which could be embedded in generated page,
so that you can restart the saved computation later on.</p>
*
* <p> To invoke a top level JavaScript function in the Controller, you use the
<tt><map:call function="function-name"/></tt> construction.</p>
*
* <p><li>to restart the computation of a previously stopped function, you use the
<tt><map:continue with="..."/></tt> construction. This restarts the computation
saved in a continuation object identified by the string value of the <tt>with</tt>
attribute. This value could be extracted in the sitemap from the requested URL, from a
POST or GET parameter etc. When the computation stored in the continuation object is
restarted, it appears as if nothing happened, all the local and global variables have
exactly the same values as they had when the computation was stopped.<br />
*
* </ul></p>
*
* <p>Once the JavaScript function in the control layer is restarted, you're
effectively inside the Controller. Here you have access to the request parameters, and
to the business logic objects. The controller script takes the appropriate actions to
invoke the business logic, usually written in Java, creating objects, setting various
values on them etc.</p>
*
* <p>When the business logic is invoked, you're inside the Model. The business
logic takes whatever actions are needed, accessing a database, making a SOAP request
to a Web service etc. When this logic finishes, the program control goes back to the
Controller.</p>
*
* <p>Once here, the Controller has to decide which page needs to be sent back to
the client browser. To do this, the script can invoke either the <tt>sendPage</tt> or
the <tt>sendPageAndContinue</tt> functions. These functions take two parameters, the
relative URL of the page to be sent back to the client, and a context object which can
be accessed inside this page to extract various values and place them in the generated
page.</p>
*
* <p>The second argument to <tt>sendPage</tt> and <tt>sendPageAndContinue</tt> is a
context object, which can be a simple dictionary with values that need to be displayed
by the View. More generally any Java or JavaScript object can be passed here, as long
as the necessary get methods for the important values are provided.</p>
*
* <p>The page specified by the URL is processed by the sitemap, using the normal
sitemap rules. The simplest case is an XSP generator followed by an XSLT
transformation and a serializer. This page generation is part of the View layer. If an
XSP page is processed, you can make use of JXPath elements to retrieve values from the
context objects passed by the Controller.</p>
*
* <p>The JXPath elements mirror similar XSLT constructions, except that instead of
operating on an XML document, operate on a Java or JavaScript object. The JXPath
logicsheet has constructs like <tt>jpath:if</tt>, <tt>jpath:choose</tt>,
<tt>jpath:when</tt>, <tt>jpath:otherwise</tt>, <tt>jpath:value-of</tt> and
<tt>jpath:for-each</tt>, which know how to operate on hierarchies of nested Java
objects. Historically the namespace is called <em>jpath</em> instead of
<em>jxpath</em>, we'll probably change it to the latter before the next major
release.</p>
*
* <p>A special instruction, <tt>jpath:continuation</tt> returns the id of the
continuation that restarts the processing from the last point. It can actually
retrieve ids of earlier continuations, which represent previous stopped points, but
I'm not discussing about this here to keep things simple.</p>
*
* <p>Going back to the <tt>sendPage</tt> and <tt>sendPageAndContinue</tt>
functions, there is a big difference between them. The first function will send the
response back to the client browser, and will stop the processing of the JavaScript
script by saving it into a continuation object. The other function,
sendPageAndContinue will send the response, but it will not stop the computation. This
is useful for example when you need to exit a top-level JavaScript function invoked
with <tt><map:call function="..."/></tt>.</p>
*
* <p>The above explains how MVC could be really achieved in Cocoon with the control
flow layer. Note that there is no direct communication between Model and View,
everything is directed by the Controller by passing to View a context object
constructed from Model data. In a perfect world, XSP should have only one logicsheet,
the JXPath logicsheet. There should be no other things in an XSP page that put logic
in the page (read View), instead of the Model. If you don't like XSP, and prefer to
use JSP or Velocity, the JXPath logicsheet equivalents should be implemented.</p>
*
* <p><h4>Basic usage</h4></p>
*
* <p>As hinted in the previous section, an application using Cocoon's MVC approach
is composed of three layers:</p>
*
* <p><ul><br />
* <li>a JavaScript controller which implements the interaction with the client</p>
*
* <p><li>the business logic model which implements your application</p>
*
* <p><li>the XSP pages, which describe the content of the pages, and XSLT
stylesheets which describe the look of the content.<br />
* </ul></p>
*
* <p>In more complex applications, the flow of pages can be thought of smaller
sequences of pages which are composed together. The natural analogy is to describe
these sequences in separate JavaScript functions, which can then be called either from
the sitemap, can call each other freely.</p>
*
* <p>An example of such an application is the user login and preferences sample
I've just checked in CVS:</p>
*
* <p><a
href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/src/webapp/samples/flow/examples/prefs";>http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/src/webapp/samples/flow/examples/prefs</a></p>
*
* <p>This application is composed of four top-level JavaScript functions:
<tt>login</tt>, <tt>registerUser</tt>, <tt>edit</tt> and <tt>logout</tt>.</p>
*
* <p>The entry level point in the application can be any of these functions, but in
order for a user to use the application, (s)he must login first. Once the user logs
in, we want to maintain the Java User object which represents the user between
top-level function invocations.</p>
*
* <p>If the script does nothing, each invocation of a top-level function starts
with fresh values for the global variables, no global state is preserved between
top-level function invocations from the sitemap. In this sample for example, the
<tt>login</tt> function assigns to the global variable <em>user</em> the Java User
object representing the logged in user. The <tt>edit</tt> function trying to operate
on this object would get a null value instead, because the value is not shared by
default between these top-level function invocations.</p>
*
* <p>To solve the problem, the <tt>login</tt> and <tt>registerUser</tt> functions
have to call the <tt>cocoon.createSession()</tt> method, which creates a servlet
session and saves the global scope containing the global variables' value in it. Next
time the user invokes one of the four top-level functions, the values of the global
variables is restored, making sharing very easy.</p>
*
* <p>Even if you don't need complex control flow in your application, you may still
choose to use the MVC pattern described above. You can have top-level JavaScript
functions which obtain the request parameters, invoke the business logic and then call
<tt>sendPageAndContinue</tt> to generate a response page and return from the
computation. Since there's no continuation object being created by this function, and
no global scope being saved, there's no memory resource being eaten. The approach
provides a clean way of separating logic and content, and makes things easy to follow,
since you have to look at a single script to understand what's going on.</p>
*/
module cocoon_flow {
/**
* Interface to a Continuation
*/
interface WebContinuation {
readonly attribute string id;
readonly attribute Object continuation;
void invalidate();
void display();
};
/**
* Interface to the Cocoon log facility.
*/
interface Log {
/**
* Log a debug message
* @param message the message
*/
void debug(in string message);
/**
* Log an information message
* @param message the message
*/
void info(in string message);
/**
* Log a warning message
* @param message the message
*/
void warn(in string message);
/**
* Log an error message
* @param message the message
*/
void error(in string message);
};
/**
* Top level object
*/
interface Global {
readonly attribute Log log;
/**
* Prints a message on standard out followed by a newline
* @param message message to be printed
*/
void print(in string message);
/**
* Passes control to the Cocoon sitemap to generate the output page
* @param uri the relative URL of the page to be sent back to the client
* @param bean a context object which can be accessed inside this page to
extract various values and place them in the generated page
*/
void sendPage(in string uri, in Object bean);
/**
* Passes control to the Cocoon sitemap to generate the output page.
* <p>The flow script is suspended after the page is generated and the whole
execution stack saved in a Continuation object </p>
* @param uri the relative URL of the page to be sent back to the client
* @param bean a context object which can be accessed inside this page to
extract various values and place them in the generated page
* @param timeToLive time to live for the continuation created
*/
void sendPageAndWait(in string uri, in Object bean, in long timeToLive);
/**
* Action Support
*
* call an action from JS
*/
void act(in string type, in string source, in Object parameters);
/**
* InputModule Support
*
* obtain value form InputModule
*/
Object inputValue(in string type, in string attribute_);
/**
* OutputModule Support
* set an attribute (starts transaction, commit or rollback required!)
*/
void outputSet(in string type, in string attribute_, in Object value);
/**
* makes attributes permanent (ends transaction)
*/
void outputCommit(in string type);
/**
* deletes attributes (ends transaction)
*/
void outputRollback(in string type);
/**
* Entry point to a flow-based XMLForm application. Replaces the
functionality
* of XMLForm actions.
* @param application Name of a JavaScript function that represents the page
flow for a form
* @param id form id
* @param validator_ns XML namespace of validator
* @param validator_doc validator document
*/
void xmlForm(in string application,
in string id, in string validator_ns,
in string validator_doc);
};
/**
* Interface to various Cocoon abstractions.
*/
interface Cocoon {
readonly attribute cocoon::Request request;
readonly attribute cocoon::Response response;
readonly attribute cocoon::Session session;
readonly attribute cocoon::Context_ context_;
readonly attribute cocoon::Environment environment;
readonly attribute cocoon::ComponentManager componentManager;
readonly attribute cocoon::StringArray parameters;
/**
* Call the Cocoon sitemap for the given URI, sending the output of the
* eventually matched pipeline to the specified outputstream.
*
* @param uri The URI for which the request should be generated.
* @param biz Extra data associated with the subrequest.
* @param out An OutputStream where the output should be written to.
* @return Whatever the Cocoon processor returns (????).
* @exception Exception If an error occurs.
*/
boolean process(in string uri, in Object object, in cocoon::OutputStream
stream);
/**
* Set the Scope object in the session object of the current
* user. This effectively means that at the next invocation from the
* sitemap of a JavaScript function (using the <map:call
* function="...">), will obtain the same scope as the current
* one.
*/
void createSession();
/**
* Remove the Scope object from the session object of the current
* user.
*/
void removeSession();
void forwardTo(in string uri, in Object bizData, in Object continuation);
void displayAllContinuations();
void callAction(in string type, in string source, in Object parameters);
Object inputModuleGetAttribute(in string type, in string attribute_);
void outputModuleSetAttribute(in string type, in string attribute_, in
Object value);
void outputModuleCommit(in string type);
void outputModuleRollback(in string type);
};
/**
* Interface to Cocoon XMLForm
*/
interface XForm {
/**
* Creates a new JavaScript wrapper of a Form object
* @see org.apache.cocoon.components.xmlform.Form
* @param id form id
* @param validatorNS Namespace of validator
* @param validatorDoc Validator document
*/
cocoon::XForm constructor(in string form_id, in string validator_namespace,
in string validator_document);
readonly attribute cocoon::XForms forms;
/**
* The model object of this form: any Any Java bean, JavaScript, DOM, or
JDOM object
*/
readonly attribute Object model;
/**
* Creates a new web continuation
* @param lastCont previous web continuation
* @param timeToLive expiration time for this continuation
*/
WebContinuation start(in WebContinuation lastCont, in long timeToLive);
/**
* Adds a violation to this form
* @param xpath xpath expression of field that contains invalid data
* @param message error message
*/
void addViolation(in string xpath, in string message);
/**
* Computes the value of an xpath expression against the model of this form
* @param expr xpath expression
* @return result of computing <code>expr</code>
*/
Object getValue(in string expr);
/**
* Sends view to presentation pipeline and waits for subsequent submission.
* Automatically resends view if validation fails.
* Creates two continuations: one immediately before the page is sent
* and one immediately after. These are used to implement automated support
* for back/forward navigation in the form. When you move forward in the
* form the second continuation is invoked. When you move back from the
* following page the first continuation is invoked.
* @param phase view to send (and phase to validate)
* @param uri presentation pipeline resource identifier
* @param validator optional function invoked to perform validation
*/
void sendView(in string phase, in string uri, in cocoon::Function validator);
/**
* Sends view to presentation pipeline but doesn't wait for submission
* @param view view to send
* @param uri presentation pipeline uri
*/
void finish(in string view, in string uri);
};
/**
* Object returned by a database query
*/
interface Result {
/**
* An array with a case-insensitive object per row with properties matching
column names and values matching column values.
*/
readonly attribute cocoon::Rows rows;
/**
* An array with an array per row of column values
*/
readonly attribute cocoon::RowsByIndex rowsByIndex;
/**
* An array of column names
*/
readonly attribute cocoon::StringArray columnNames;
/**
* Number of rows returned
*/
readonly attribute long rowCount;
/**
* True if not all rows are included due to reaching a maximum value
*/
readonly attribute boolean isLimitedByMaxRows;
};
/**
* High level interface to JDBC operations modeled after JSTL
*/
interface Database {
/**
* Used to execute INSERT, UPDATE, and DELETE statements, as well as
statements that create or remove database objects, such as CREATE TABLE and DROP
TABLE. It returns the number of rows affected by the statement.
* @param sql SQL statement to execute
* @return the number of rows affected
*/
long update(in string sql);
/**
* Executes a SQL SELECT statement. You can limit the result with startRow
and maxRows (which are optional).
* @param sql SQL statement to execute
* @return Result: contains the same properties as in JSTL.
*/
Result query(in string sql);
};
};
