cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From p...@apache.org
Subject cvs commit: xml-cocoon2/src/idl/cocoon_flow _cocoon_flow_module.idl cocoon_flow.idl
Date Sat, 08 Mar 2003 19:54:50 GMT
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:apache@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  <mailto:stefano@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>&lt;map:call&nbsp;function="function-name"/&gt;</code>
   *       construction.
   *     </li>
   *     <li>
   *       To restart the computation of a previously stopped function, you use
   *       the <code>&lt;map:continue&nbsp;with="..."/&gt;</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>&lt;map:call&nbsp;function="..."/&gt;</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 &copy; 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"
  
  };
  
  
  

Mime
View raw message