home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / using.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  7.9 KB  |  191 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.   <header>
  21.     <title>Advanced Control Flow</title>
  22.     <authors>
  23.       <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
  24.     </authors>
  25.   </header>
  26.  
  27.   <body>
  28.   <s1 title="Using Cocoon's Control Flow">
  29.   <p>
  30.     The general flow of actions in an application which uses the control flow
  31.     is as described below.
  32.   </p>
  33.  
  34.   <p>
  35.     The request is received by Cocoon and passed to the sitemap for
  36.     processing. In the sitemap, you can do two things to pass the control to
  37.     the Control Flow layer:</p>
  38.   <ul>
  39.     <li>
  40.       You can invoke a JavaScript top-level function to start processing a
  41.       logically grouped sequences of pages. Each time a response page is
  42.       being sent back to the client browser from this function, the
  43.       processing of the JavaScript  code stops at the point the page is
  44.       sent back, and the HTTP request finishes. Through the magic of
  45.       continuations, the execution state is saved in a continuation object.
  46.       Each continuation is given a unique string id, which could be embedded
  47.       in generated page, so that you can restart the saved computation later
  48.       on.
  49.     </li>
  50.     <li>
  51.       To invoke a top level JavaScript function in the Control Flow, you use
  52.       the <link href="sitemap.html#callFunction"><code><map:call function="function-name"/></code></link>
  53.       construction.
  54.     </li>
  55.     <li>
  56.       To restart the computation of a previously stopped function, you use
  57.       the <link href="sitemap.html#callContinuation"><code><map:call continuation="..."/></code></link> construction.
  58.       This restarts the computation saved in a continuation object
  59.       identified by the string value of the <code>continuation</code> attribute.
  60.       This value could be extracted in the sitemap from the requested URL,
  61.       from a POST or GET parameter etc. When the computation stored in the
  62.       continuation object is restarted, it appears as if nothing happened,
  63.       all the local and global variables have exactly the same values as
  64.       they had when the computation was stopped.
  65.     </li>
  66.   </ul>
  67.  
  68.   <p>
  69.     Once the JavaScript function in the control layer is restarted, you're
  70.     effectively inside the Control Flow. Here you have access to the request
  71.     parameters, and to the business logic objects. The controller script
  72.     takes the appropriate actions to invoke the business logic, usually
  73.     written in Java, creating objects, setting various values on them etc...
  74.   </p>
  75.  
  76.   <p>
  77.     When the business logic is invoked, you're inside the Model. The business
  78.     logic takes whatever actions are needed, accessing a database, making a
  79.     SOAP request to a Web service etc. When this logic finishes, the program
  80.     control goes back to the Control Flow.
  81.   </p>
  82.  
  83.   <p>
  84.     Once here, the Control Flow has to decide which page needs to be sent back
  85.     to the client browser. To do this, the script can invoke one of the
  86.     <link href="api.html#sendPageAndWait"><code>cocoon.sendPageAndWait()</code></link> or <link href="api.html#sendPage"><code>cocoon.sendPage()</code></link> functions.
  87.     These functions take two parameters, the relative URL of the page to be
  88.     sent back to the client, and a context object which can be accessed
  89.     inside this page to extract various values and place them in the
  90.     generated page.
  91.   </p>
  92.  
  93.   <p>
  94.     The second argument to <code>cocoon.sendPageAndWait()</code> and
  95.     <code>cocoon.sendPage()</code> is a context object, which can be a
  96.     simple dictionary with values that need to be displayed by the View. More
  97.     generally any Java or JavaScript object can be passed here, as long as
  98.     the necessary get methods for the important values are provided.
  99.   </p>
  100.  
  101.   <p>
  102.     The page specified by the URL is processed by the sitemap, using the
  103.     normal sitemap rules. The simplest case is a <link href="views.html">generator</link> followed by
  104.     an XSLT transformation and a serializer. This page generation is part of
  105.     the View layer. To process a page you can make use of several
  106.     Cocoon <link href="views.html">generators</link> to retrieve values from the context objects passed by the
  107.     Control Flow.
  108.   </p>
  109.  
  110.   <p>
  111.     Going back to the <code>cocoon.sendPageAndWait()</code> and
  112.     <code>sendPage()</code> functions, there is a big difference
  113.     between them. The first function will send the response back to the
  114.     client browser, and will stop the processing of the JavaScript script by
  115.     saving it into a continuation object. The other function,
  116.     <code>cocoon.sendPage()</code> will send the response, but it will not
  117.     stop the computation. This is useful for example when you need to exit a
  118.     top-level JavaScript function invoked with
  119.     <code><map:call function="..."/></code>.
  120.   </p>
  121.  
  122.   <p>
  123.     The above explains how MVC could be really achieved in Cocoon with the
  124.     control flow layer. Note that there is no direct communication between
  125.     Model and View, everything is directed by the Control Flow by passing to
  126.     View a context object constructed from Model data.
  127.   </p>
  128.  
  129.   <s2 title="Basic usage">
  130.  
  131.   <p>
  132.     As hinted in the previous section, an application using Cocoon's MVC
  133.     approach is composed of three layers:</p>
  134.   <ul>
  135.     <li>
  136.       A JavaScript controller which implements the interaction with the
  137.       client
  138.     </li>
  139.     <li>
  140.      The business logic model which implements your application
  141.     </li>
  142.     <li>
  143.       The <link href="views.html">page templates</link>, which describe the content of the pages, and XSLT
  144.       stylesheets which describe the look of the content.
  145.     </li>
  146.   </ul>
  147.  
  148.   <p>
  149.     In more complex applications, the flow of pages can be thought of smaller
  150.     sequences of pages which are composed together. The natural analogy is to
  151.     describe these sequences in separate JavaScript functions, which can then
  152.     be called either from the sitemap, can call each other freely.
  153.   </p>
  154.  
  155.   <p>
  156.     An example of such an application is the user login and preferences
  157.     sample 
  158.   </p>
  159.  
  160.   <p>
  161.     This application is composed of four top-level JavaScript functions:</p>
  162.   <ul>
  163.     <li><code>login</code>,</li>
  164.     <li><code>registerUser</code>,</li>
  165.     <li><code>edit</code> and</li>
  166.     <li><code>logout</code>.</li>
  167.   </ul>
  168.  
  169.   <p>
  170.     The entry level point in the application can be any of these functions,
  171.     but in order for a user to use the application, (s)he must login first.
  172.     Once the user logs in, we want to maintain the Java User object which
  173.     represents the user between top-level function invocations.
  174.   </p>
  175.   <p>
  176.     Even if you don't need complex control flow in your application, you may
  177.     still choose to use the MVC pattern described above. You can have top-
  178.     level JavaScript functions which obtain the request parameters, invoke
  179.     the business logic and then call <code>cocoon.sendPage()</code> to
  180.     generate a response page and return from the computation. Since there's
  181.     no continuation object being created by this function, and no global
  182.     scope being saved, there's no memory resource being eaten. The approach
  183.     provides a clean way of separating logic and content, and makes things
  184.     easy to follow, since you have to look at a single script to understand
  185.     what's going on.
  186.   </p>
  187.   </s2>
  188.     </s1>
  189.   </body>
  190. </document>
  191.