You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by pi...@apache.org on 2003/03/08 20:54:50 UTC
cvs commit: xml-cocoon2/src/idl/cocoon_flow _cocoon_flow_module.idl cocoon_flow.idl
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 *
* <ma...@apache.org>. *
* *
* 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 <ma...@apache.org>. 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"
};