Return-Path: Delivered-To: apmail-xml-cocoon-cvs-archive@xml.apache.org Received: (qmail 12753 invoked by uid 500); 8 Mar 2003 19:54:51 -0000 Mailing-List: contact cocoon-cvs-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: cocoon-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list cocoon-cvs@xml.apache.org Received: (qmail 12739 invoked by uid 500); 8 Mar 2003 19:54:51 -0000 Delivered-To: apmail-xml-cocoon2-cvs@apache.org Received: (qmail 12735 invoked from network); 8 Mar 2003 19:54:51 -0000 Received: from icarus.apache.org (208.185.179.13) by daedalus.apache.org with SMTP; 8 Mar 2003 19:54:51 -0000 Received: (qmail 19392 invoked by uid 1023); 8 Mar 2003 19:54:50 -0000 Date: 8 Mar 2003 19:54:50 -0000 Message-ID: <20030308195450.19391.qmail@icarus.apache.org> From: pier@apache.org To: xml-cocoon2-cvs@apache.org Subject: cvs commit: xml-cocoon2/src/idl/cocoon_flow _cocoon_flow_module.idl cocoon_flow.idl X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 ." * * * * 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 * * . * * * * 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 . For more information * * about the Apache Software Foundation please see . * * * * ------------------------------------------------------------------------- */ /** *

* The general flow of actions in an application which uses the control flow * is as described below. *

* *

* 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: *

    *
  • * 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. *
    • *
  • * To invoke a top level JavaScript function in the Controller, you use * the <map:call function="function-name"/> * construction. *
    • *
  • * To restart the computation of a previously stopped function, you use * the <map:continue with="..."/> construction. * This restarts the computation saved in a continuation object * identified by the string value of the with 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. *
    • *
*

* *

* 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... *

* *

* 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. *

* *

* 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 * sendPage or the sendPageAndContinue 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. *

* *

* The second argument to sendPage and * sendPageAndContinue 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. *

* *

* 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. *

* *

* 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 *

    *
  • jpath:if,
    • *
  • jpath:choose,
    • *
  • jpath:when,
    • *
  • jpath:otherwise,
    • *
  • jpath:value-of and
    • *
  • jpath:for-each,
    • *
* which know how to operate on hierarchies of nested Java objects. * Historically the namespace is called jpath instead of * jxpath, we'll probably change it to the latter before the next * major release. *

* *

* A special instruction, jpath:continuation 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. *

* *

* Going back to the sendPage and * sendPageAndContinue 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 * <map:call function="..."/>. *

* *

* 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. *

* *

Basic usage

* *

* As hinted in the previous section, an application using Cocoon's MVC * approach is composed of three layers: *

    *
  • * A JavaScript controller which implements the interaction with the * client *
    • *
  • * The business logic model which implements your application *
    • *
  • * The XSP pages, which describe the content of the pages, and XSLT * stylesheets which describe the look of the content. *
    • *
*

* *

* 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. *

* *

* An example of such an application is the user login and preferences * sample I've just checked into the * Cocoon CVS *

* *

* This application is composed of four top-level JavaScript functions: *

    *
  • login,
    • *
  • registerUser,
    • *
  • edit and
    • *
  • logout.
    • *
*

* *

* 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. *

* *

* 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 login function assigns to the * global variable user the Java User object representing the * logged in user. The edit 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. *

* *

* To solve the problem, the login and * registerUser functions have to call the * cocoon.createSession() 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. *

* *

* 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 sendPageAndContinue 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. *

* *

* Originally taken from * Ovidiu Predescu's Weblog. *

* *

*

*
Authors:
*
* Ovidiu Predescu, * Christopher Oliver. *
*
Copyright:
*
* Copyright © 2002-2003 * The Apache Software Foundation. * All rights reserved. *
*
*

*/ 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" };