cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From stef...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/flow samples.xml invalidContinuation.xml index.xml book.xml continuations.xml how-does-it-work.xml
Date Tue, 25 Mar 2003 13:43:33 GMT
stefano     2003/03/25 05:43:33

  Added:       src/documentation/xdocs/userdocs/flow samples.xml
                        invalidContinuation.xml index.xml book.xml
                        continuations.xml how-does-it-work.xml
  Log:
  moving flow documents into the xdocs (where they belong)
  
  Revision  Changes    Path
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/samples.xml
  
  Index: samples.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Apache Cocoon - Examples</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="Examples">
        <p>This page contains shows some examples built using the
        control flow layer available in Cocoon.</p>
  
        <ul>
  	<li><link href="examples/calc/">Calculator</link> - a simple
  	example using continuations to maintain the state between
  	requests.</li>
  
  	<li><link href="examples/prefs/">User preferences</link> - A
  	common portion of an application which requires users to be
  	registered.</li>
        </ul>
      </s1>
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/invalidContinuation.xml
  
  Index: invalidContinuation.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>404 Error</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="Error">
        <p>You have reached an inexistent page: either your session has
        expired or the page you were referred to was invalid.</p>
      </s1>
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Apache Cocoon - Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
    <body>
      <s1 title="Control flow">
        <p>Cocoon has advanced control flow, the ability to describe the
        order of Web pages that have to be sent to the client, at any
        given point in time in an application.</p>
  
        <p>Traditional Web applications try to model the control flow of
        a Web application by modeling the application as a finite state
        machine (FSM). In this model, the Web application is composed of
        multiple states, but the application can be only in one state at
        a time. Any request received by the application transitions it
        in a different state. During such a transition, the application
        may perform various side-effects, such as updating objects
        either in memory or in a database. Another important side-effect
        of such a transition is that a Web page is sent back to the
        client browser.</p>
  
        <p>For simple Web applications, this model works fine. However,
        as the application grows, the number of states and transitions
        between them grows as well, and it becomes hard to visualize
        what's happening in the application.</p>
  
        <p>Moreover, the interactions in some applications are more
        complex than a simple finite state machine. In such cases it's
        much easier to think and implement the application as a program,
        rather than a FSM.</p>
  
        <p>By using a high level programming concept called
        <em>continuations</em>, Cocoon tries to solve this problem, and
        promises to allow the control flow in Web applications to be
        modeled as a normal program.</p>
  
      </s1>
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/book.xml
  
  Index: book.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../../../WEB-INF/entities/book-cocoon-v10.dtd">
  
  <book software="Apache Cocoon" 
        title="Apache Schecoon Documentation" 
        copyright="1999-2003 The Apache Software Foundation"
        xmlns:xlink="http://www.w3.org/1999/xlink">
  
    <menu label="Documentation">
      <menu-item label="Back to Cocoon" href="../"/>
      <menu-item label="Introduction" href="index.html"/>
      <menu-item label="Continuations" href="continuations.html"/>
      <menu-item label="How does it work?" href="how-does-it-work.html"/>
      <menu-item label="Examples" href="samples.html"/>
    </menu>
  </book>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/continuations.xml
  
  Index: continuations.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="A different approach">
        <p>Web applications are essentially event-driven
        applications. Such applications have to react to events
        generated from the client browser, and they respond to these
        perhaps by changing their internal state and generating a
        response.</p>
  
        <p>The result is that even a simple application that needs to
        collect some information from the user using more than one page,
        has to somehow maintain the input accumulated so far from the
        user. This input is a characteristic of the application
        state. Another characteristic of the application state is where
        the program processing is.</p>
  
        <p>Let's look at an example. Suppose we want to write a very
        simple calculator, which collects the numbers to be added, as
        well as the operator, each in a separate page. It would be very
        nice if we could write something like this:</p>
  
        <source><![CDATA[
  function calculator()
  {
    var a, b, operator;
  
    sendPageAndWait("getA.html");
    a = request.getParameter("a");
  
    sendPageAndWait("getB.html");
    b = request.getParameter("b");
  
    sendPageAndWait("getOperator.html");
    operator = request.getParameter("op");
  
    try {
      if (operator == "plus")
        sendPage("result.html", a + b);
      else if (operator == "minus")
        sendPage("result.html", a - b);
      else if (operator == "multiply")
        sendPage("result.html", a * b);
      else if (operator == "divide")
        sendPage("result.html", a / b);
      else
        sendResult("invalidOperator.html");
    }
    catch (Exception ex) {
      sendResult("error.html", "Operation failed: " + ex.toString();
    }
  }
  ]]></source>
  
        <p>In this example, the <code>calculator</code> function is
        called to start the calculator application. We'd like the
        <code>sendPageAndWait</code> function to be a special function, that
        takes as arguments an HTML file to be sent as response, and some
        optional data that needs to be placed dynamically in it. We
        would like <code>sendPageAndWait</code> to send the response page and
        then block the executing thread, until the user clicks on a link
        in the response page, which sends a request back to the
        server. This request resumes the processing at the point it was
        left, right after the call to <code>sendPageAndWait</code>.</p>
  
        <p>This approach looks very powerful, since the flow of pages
        within the application can be described as a normal
        program. Using this approach you no longer have to think of your
        Web application as a finite state machine, which transitions
        from one state to another, and in the process generates response
        pages.</p>
  
        <p>A big disadvantage of the approach above is that we need to
        maintain a thread alive until the user hits the link on the
        response page. This is clearly very expensive!</p>
  
        <p>It would be very nice if we can capture the state of the
        application, its stack of function calls, which includes local
        variables, the global variables and the program counter, and
        save them into an object. If this object would give us the
        ability to restart the processing from the point stored in it,
        this would be what we need!</p>
  
        <s2 title="What are continuations?">
  
  	<p>A continuation is exactly the type of object that we need.
  	Think of a continuation as an object that, for a given point
  	in your program, contains a snapshot of the stack trace,
  	including all the local variables, and the program
  	counter. You can not only store these things in the
  	continuation object, but also restore the execution of the
  	program from a continuation object. This means that the stack
  	trace and the program counter of the running program become
  	the ones stored in a continuation.</p>
  
  	<p>Continuations are powerful concepts from the world of
  	functional languages, like <link
  	href="http://www.schemers.org/">Scheme</link>, but they are
  	becoming popular in other languages as well.</p>
  
      </s2>
  
    </s1>
  
    </body>
  </document>
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/flow/how-does-it-work.xml
  
  Index: how-does-it-work.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../../WEB-INF/entities/document-v10.dtd">
  
  <document>
    <header>
      <title>Advanced Control Flow</title>
      <authors>
        <person name="Ovidiu Predescu" email="ovidiu@apache.org"/>
      </authors>
    </header>
  
    <body>
      <s1 title="Cocoon and continuations">
  	<p>With continuations in the language, you can essentially
  	store the continuation of <code>sendPageAndWait</code> (think of all
  	the stack trace, and the program counter), put it in a global
  	hash table associated with an id. The id is then encoded in
  	the <code>response.xml</code> page as an URL. When the user
  	clicks on that URL, on the server side the associated
  	continuation is resumed. Resuming the processing happens as if
  	nothing was stopped, you get all the stack trace back, and all
  	the local variables.</p>
  
  	<p>So instead of using beans to store things in session, you
  	use normal variables in a program. Since each user has its own
  	version of the program, all the local variables in the program
  	are separate between users.</p>
  
  	<p>With this approach clicking the <em>Back</em> button in the
  	browser is no longer a hassle to deal with for you as a
  	server-side programmer. They will simply refer to past
  	continuations objects, which have their own state of the local
  	variables.</p>
  
  	<p>Since continuations are objects, you can also store them in
  	a database, for really long-lived session, just like you do
  	with session beans.</p>
      </s1>
  
    </body>
  </document>
  
  
  

Mime
View raw message