pier 2003/03/08 11:54:50
Modified: src/idl main.idl Added: src/idl/cocoon_flow _cocoon_flow_module.idl Removed: src/idl/cocoon_flow cocoon_flow.idl Log: Better naming for IDL modules definitions. Revision Changes Path 1.4 +1 -1 xml-cocoon2/src/idl/main.idl Index: main.idl =================================================================== RCS file: /home/cvs/xml-cocoon2/src/idl/main.idl,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- main.idl 8 Mar 2003 19:50:10 -0000 1.3 +++ main.idl 8 Mar 2003 19:54:50 -0000 1.4 @@ -1,2 +1,2 @@ #include "cocoon/_cocoon_module.idl" -#include "cocoon_flow/cocoon_flow.idl" +#include "cocoon_flow/_cocoon_flow_module.idl" 1.1 xml-cocoon2/src/idl/cocoon_flow/_cocoon_flow_module.idl Index: _cocoon_flow_module.idl =================================================================== /* ========================================================================= * * The Apache Software License, Version 1.1 * * ========================================================================= * * Copyright (C) 1999-2003 The Apache Software Foundation. * * All rights reserved. * * * * Redistribution and use in source and binary forms, with or without * * modification, are permitted provided that the following conditions are * * met: * * * * 1. Redistributions of source code must retain the above copyright notice, * * this list of conditions and the following disclaimer. * * * * 2. Redistributions in binary form must reproduce the above copyright * * notice, this list of conditions and the following disclaimer in the * * documentation and/or other materials provided with the distribution. * * * * 3. The end-user documentation included with the redistribution, if any, * * must include the following acknowledgment: * * * * "This product includes software developed by the * * Apache Software Foundation <http://www.apache.org/>." * * * * Alternately, this acknowledgment may appear in the software itself, if * * and wherever such third-party acknowledgments normally appear. * * * * 4. The names "Apache Cocoon" and "Apache Software Foundation" must not be * * used to endorse or promote products derived from this software without * * prior written permission. For written permission, please contact * * <mailto:[EMAIL PROTECTED]>. * * * * 5. Products derived from this software may not be called "Apache", nor * * may "Apache" appear in their name, without prior written permission of * * the Apache Software Foundation. * * * * ------------------------------------------------------------------------- * * * * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES * * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY * * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL * * THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY * * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGE * * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVI- * * CES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER * * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABI- * * LITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH * * DAMAGE. * * * * This software consists of voluntary contributions made by many individua- * * ls on behalf of the Apache Software Foundation and was originally created * * by Stefano Mazzocchi <mailto:[EMAIL PROTECTED]>. For more information * * about the Apache Software Foundation please see <http://www.apache.org/>. * * * * ------------------------------------------------------------------------- */ /** * <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> * * <p> * Originally taken from * <a href="http://www.webweavertech.com/ovidiu/weblog/archives/000042.html"; * >Ovidiu Predescu's Weblog</a>. * </p> * * <p> * <dl> * <dt><b>Authors:</b></dt> * <dd> * <a href="mailto:ovidiu AT apache.org">Ovidiu Predescu</a>, * <a href="mailto:coliver AT apache.org">Christopher Oliver</a>. * </dd> * <dt><b>Copyright:</b></dt> * <dd> * Copyright © 2002-2003 * <a href="http://www.apache.org/";>The Apache Software Foundation</a>. * All rights reserved. * </dd> * </dl> * </p> */ module cocoon_flow { interface Cocoon; interface Database; interface Global; interface Log; interface Result; interface WebContinuation; interface XForm; #include "cocoon_flow/Cocoon.idl" #include "cocoon_flow/Database.idl" #include "cocoon_flow/Global.idl" #include "cocoon_flow/Log.idl" #include "cocoon_flow/Result.idl" #include "cocoon_flow/WebContinuation.idl" #include "cocoon_flow/XForm.idl" };
