pier 2003/03/08 10:30:51
Modified: src/idl/cocoon_flow cocoon_flow.idl Log: Starting to improve readability of the IDL Flow sources so that others are actually helped in contributing to them. Revision Changes Path 1.6 +274 -121 xml-cocoon2/src/idl/cocoon_flow/cocoon_flow.idl Index: cocoon_flow.idl =================================================================== RCS file: /home/cvs/xml-cocoon2/src/idl/cocoon_flow/cocoon_flow.idl,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- cocoon_flow.idl 6 Mar 2003 19:25:37 -0000 1.5 +++ cocoon_flow.idl 8 Mar 2003 18:30:50 -0000 1.6 @@ -1,67 +1,220 @@ -#include "cocoon/cocoon.idl" - // Taken from http://www.webweavertech.com/ovidiu/weblog/archives/000042.html /** - * <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> -*/ + * <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: + * <ul> + * <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. + * </li> + * <li> + * To invoke a top level JavaScript function in the Controller, you use + * the <code><map:call function="function-name"/></code> + * construction. + * </li> + * <li> + * To restart the computation of a previously stopped function, you use + * the <code><map:continue with="..."/></code> construction. + * This restarts the computation saved in a continuation object + * identified by the string value of the <code>with</code> 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. + * </li> + * </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 + * <code>sendPage</code> or the <code>sendPageAndContinue</code> 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 <code>sendPage</code> and + * <code>sendPageAndContinue</code> 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 + * <ul> + * <li><code>jpath:if</code>,</li> + * <li><code>jpath:choose</code>,</li> + * <li><code>jpath:when</code>,</li> + * <li><code>jpath:otherwise</code>,</li> + * <li><code>jpath:value-of</code> and</li> + * <li><code>jpath:for-each</code>,</li> + * </ul> + * 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, <code>jpath:continuation</code> 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 <code>sendPage</code> and + * <code>sendPageAndContinue</code> 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, + * <code>sendPageAndContinue</code> 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 + * <code><map:call function="..."/></code>. + * </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> + * + * <h4>Basic usage</h4> + * + * <p> + * As hinted in the previous section, an application using Cocoon's MVC + * approach is composed of three layers: + * <ul> + * <li> + * A JavaScript controller which implements the interaction with the + * client + * </li> + * <li> + * The business logic model which implements your application + * </li> + * <li> + * The XSP pages, which describe the content of the pages, and XSLT + * stylesheets which describe the look of the content. + * </li> + * </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 into the + * <a href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/src/webapp/samples/flow/examples/prefs"; + * >Cocoon CVS</a> + * </p> + * + * <p> + * This application is composed of four top-level JavaScript functions: + * <ul> + * <li><code>login</code>,</li> + * <li><code>registerUser</code>,</li> + * <li><code>edit</code> and</li> + * <li><code>logout</code>.</li> + * </ul> + * </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 <code>login</code> function assigns to the + * global variable <em>user</em> the Java User object representing the + * logged in user. The <code>edit</code> 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 <code>login</code> and + * <code>registerUser</code> functions have to call the + * <code>cocoon.createSession()</code> 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 <code>sendPageAndContinue</code> 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 { @@ -78,22 +231,22 @@ * <code>WebContinuation</code>s.</p> */ interface WebContinuation { - /** - * Unguessable unique identifier of this object - */ + /** + * Unguessable unique identifier of this object + */ readonly attribute string id; - /** - * Current continuation - */ + /** + * Current continuation + */ readonly attribute cocoon::Continuation continuation; - /** - * Deletes this continuation together with all of its children - */ + /** + * Deletes this continuation together with all of its children + */ void invalidate(); - /** - * Debugging aid that displays the tree of continuations rooted - * in this object - */ + /** + * Debugging aid that displays the tree of continuations rooted + * in this object + */ void display(); }; @@ -129,8 +282,8 @@ interface Global { /** - * Reference to the logging facility - */ + * Reference to the logging facility + */ readonly attribute Log log; /** @@ -157,40 +310,40 @@ */ WebContinuation sendPageAndWait(in string uri, in Object bean, in long timeToLive); - // Action Support + // Action Support /** * Call an action from JS */ void act(in string type, in string source, in Object parameters); - // InputModule Support + // InputModule Support /** * Obtain value from InputModule - * @param type - * @param attribute_ + * @param type + * @param attribute_ */ Object inputValue(in string type, in string attribute_); - // OutputModule Support + // OutputModule Support /** * Set an attribute (starts transaction, commit or rollback required!) - * @param type (not sure) - * @param attribute_ (not sure) - * @param value (not sure) + * @param type (not sure) + * @param attribute_ (not sure) + * @param value (not sure) */ void outputSet(in string type, in string attribute_, in Object value); /** * Makes attributes permanent (ends transaction) - * @param type (not sure) + * @param type (not sure) */ void outputCommit(in string type); /** * Deletes attributes (ends transaction) - * @param type (not sure) + * @param type (not sure) */ void outputRollback(in string type); @@ -250,29 +403,29 @@ void removeSession(); - /** - * Forward the request to a Cocoon pipeline. - * - * @param URI a <code>String</code>, the URI of the forwarded request - * @param bizData an <code>Object</code>, the business data object - * to be made available to the forwarded pipeline - * @param continuation a <code>WebContinuation</code>, the - * continuation to be called to resume the processing - */ + /** + * Forward the request to a Cocoon pipeline. + * + * @param URI a <code>String</code>, the URI of the forwarded request + * @param bizData an <code>Object</code>, the business data object + * to be made available to the forwarded pipeline + * @param continuation a <code>WebContinuation</code>, the + * continuation to be called to resume the processing + */ void forwardTo(in string uri, in Object bizData, in WebContinuation continuation); - /** - * Load the file specified as argument. - * @param filename a <code>String</code> value - * @return an <code>Object</code> value - */ - - Object load(in string filename); - - /** - * Dump to Log file all <code>WebContinuation</code>s - * in the system - */ + /** + * Load the file specified as argument. + * @param filename a <code>String</code> value + * @return an <code>Object</code> value + */ + + Object load(in string filename); + + /** + * Dump to Log file all <code>WebContinuation</code>s + * in the system + */ void displayAllContinuations(); /** @@ -281,28 +434,28 @@ void callAction(in string type, in string source, in Object parameters); /** * Obtain value from InputModule - * @param type (not sure) - * @param attribute_ (not sure) + * @param type (not sure) + * @param attribute_ (not sure) */ Object inputModuleGetAttribute(in string type, in string attribute_); /** * Set an attribute (starts transaction, commit or rollback required!) - * @param type (not sure) - * @param attribute_ (not sure) - * @param value (not sure) + * @param type (not sure) + * @param attribute_ (not sure) + * @param value (not sure) */ void outputModuleSetAttribute(in string type, in string attribute_, in Object value); /** * Makes attributes permanent (ends transaction) - * @param type (not sure) + * @param type (not sure) */ void outputModuleCommit(in string type); /** * Deletes attributes (ends transaction) - * @param type (not sure) + * @param type (not sure) */ void outputModuleRollback(in string type); @@ -324,9 +477,9 @@ */ cocoon::XForm constructor(in string form_id, in string validator_namespace, in string validator_document); - /** - * Global variable that stores XForm instances by id - */ + /** + * Global variable that stores XForm instances by id + */ readonly attribute cocoon::XForms forms; /** @@ -359,7 +512,7 @@ /** * Returns an iterator over a nodeset value of an xpath expression - * evaluated against the model of this form + * evaluated against the model of this form * @param expr xpath expression * @return java.util.Iterator representing a nodeset */ @@ -431,8 +584,8 @@ /** * Executes a SQL SELECT statement. You can limit the result with startRow and maxRows (which are optional). * @param sql SQL statement to execute - * @param startRow first row to be returned in result - * @param maxRows maximum number of rows to return in result + * @param startRow first row to be returned in result + * @param maxRows maximum number of rows to return in result * @return Result: contains the same properties as in JSTL. */ Result query(in string sql, in long startRow, in long maxRows);
