crafterm 2002/12/11 10:55:28
Modified: src/documentation/xdocs/howto book.xml index.xml
Added: src/documentation/images flow-debugger.jpg
src/documentation/xdocs/howto howto-flow-debugger.xml
Log:
Initial version of the flow debugger howto.
Revision Changes Path
1.1 xml-cocoon2/src/documentation/images/flow-debugger.jpg
<<Binary file>>
1.12 +1 -0 xml-cocoon2/src/documentation/xdocs/howto/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/book.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- book.xml 1 Nov 2002 13:17:12 -0000 1.11
+++ book.xml 11 Dec 2002 18:55:28 -0000 1.12
@@ -14,6 +14,7 @@
<menu-item label="Web Syndication"
href="../userdocs/generators/wsproxy-generator.html"/>
<menu-item label="Chaperon" href="chaperon/howto-chaperon-intro.html"/>
<menu-item label="i18n XMLForm" href="howto-i18n-xmlform.html"/>
+ <menu-item label="Flow Debugger" href="howto-flow-debugger.html"/>
</menu>
<menu label="Documentation">
<menu-item label="Author How-To" href="howto-author-howto.html"/>
1.12 +1 -0 xml-cocoon2/src/documentation/xdocs/howto/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/index.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- index.xml 1 Nov 2002 13:17:12 -0000 1.11
+++ index.xml 11 Dec 2002 18:55:28 -0000 1.12
@@ -26,6 +26,7 @@
<li><link href="howto-html-pdf-publishing.html">HTML-PDF Publishing</link></li>
<li><link href="chaperon/howto-chaperon-intro.html">Chaperon Text Parser</link></li>
<li><link href="howto-i18n-xmlform.html">i18n XMLForm</link></li>
+<li><link href="howto-flow-debugger.html">Flow Debugger</link></li>
</ul>
</s2>
1.1
xml-cocoon2/src/documentation/xdocs/howto/howto-flow-debugger.xml
Index: howto-flow-debugger.xml
===================================================================
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to use the Cocoon Flow Debugger</title>
<authors>
<person name="Marcus Crafter" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This how-to describes how to enable and start the flow debugger in
Cocoon Web Applications that use the JavaScript based flow engine. The flow debugger
allows you to visually debug flow scripts using breakpoints, tracing, variable
watches, etc, similar to other common visual debugging environments currently
available.
</p>
<p>
For a full description of how to use the debugger itself, please refer
to the Mozilla Rhino debugger <link
href="http://www.mozilla.org/rhino/debugger.html";>page</link>.
</p>
</s1>
<s1 title="Purpose">
<p>
The process of writing and debugging flow script can be tedious and
repetitive. JavaScript is a language that features typed objects but untyped
references, which means at times it can be difficult to locate programming errors
until runtime.
</p>
<p>
The flow debugger intends to ease the development, debugging and
maintenance of flow scripts by allowing you to visually inspect and influence your
flow script, while it's running, without having to resort to many superfluous print or
log statements.
</p>
</s1>
<s1 title="Intended Audience">
<p>
This document is intended for Cocoon web application developers who
are using the JavaScript flow engine inside of their Cocoon application.
</p>
</s1>
<s1 title="Prerequisites">
<p>
Until Cocoon 2.1 is released, to use the flow debugger you will need a
CVS <link href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/";>version</link> or
development <link href="http://xml.apache.org/from-cvs/xml-cocoon2/";>snapshot</link>
of Cocoon, at least as recent as 7th December 2002.
</p>
<p>
You will also need a JavaScript flow based web application, for
example the flow webapp samples that are currently shipped with Cocoon, and you will
need to be running Cocoon on a server that has a display attached (either local or
remote).
</p>
<p>
No special files need to be installed to use the debugger, support for
the debugger is included in the Rhino jar file which is part of Cocoon.
</p>
</s1>
<s1 title="Steps">
<p>
The process of enabling and starting the debugger is quite simple.
Essentially, all you have to is enable support for the debugger in the JavaScript
interpreter's configuration section of the cocoon.xconf file, and start your
application. The debugger will be instantiated by the next request that invokes
<code>map:call function</code> or <code>continuation</code>.
</p>
<p>
Once the debugger is up and running, it should look similar to
<link href="images/flow-debugger.jpg">this</link>. So, let's get
started.
</p>
<s2 title="Configuration">
<p>
By default, the flow debugger is disabled. To enable it, you will
need to modify the cocoon.xconf file to include one element named
<strong>debugger</strong>, which contains the value <em>enabled</em>, as follows:
</p>
<source>
<?xml version="1.0"?>
<flow-interpreters default="JavaScript" logger="flow">
<component-instance name="JavaScript"
class="org.apache.cocoon.components.flow.javascript.JavaScriptInterpreter">
<load-on-startup>resource://org/apache/cocoon/components/flow/javascript/system.js</load-on-startup>
<reload-scripts>true</reload-scripts>
<check-time>4000</check-time>
<strong><debugger>enabled</debugger></strong> <!--
JavaScript Debugger support -->
</component-instance>
</flow-interpreters>
</source>
<note>If you are using the debugger with the Cocoon flow samples, you
will need to modify the <em>cocoon.xconf</em> file in build/cocoon/webapp/WEB-INF, or
the <em>flow.xconf</em> file in src/java/org/apache/cocoon/components/flow/, which is
merged into the cocoon.xconf file at build time</note>
</s2>
<s2 title="Compile and start your environment">
<p>
Compile and start your application as normal.
</p>
</s2>
<s2 title="Start the flow engine">
<p>
Once your application is running and awaiting requests, attempt to
access a page that calls a flow function. The invocation will take longer than normal,
but on your server's display you should see the visual debugger being created and
populated with your flow script.
</p>
<note>Portions of Cocoon's flow script management <link
href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/src/java/org/apache/cocoon/components/flow/javascript/system.js?rev=HEAD&content-type=text/vnd.viewcvs-markup";>code</link>
will also be viewable in the debugger.</note>
<p>
A debugger instance is created per JavaScript interpreter. This
means if you make another request to a different sitemap for example, a new debugger
instance will be created alongside the previous one. This allows you to debug flow
scripts locally to the sitemap they are defined in.
</p>
</s2>
<s2 title="Use the debugger">
<p>
At this stage, the debugger is in control. By default, all entry
points into the debugger result in an automatic breakpoint being set at that entry
point (ie. at the beginning of each call function and handle continuation invocation).
To continue processing, press any of the <em>step</em> buttons to trace through your
code.
</p>
<note>Pressing <em>Exit</em> from the <em>File</em> menu will not
actually exit the debugger or JVM, but will make it invisible. It will be
automatically made visible again upon entering a new call-function/handle-continuation
frame.</note>
<p>
Using the flow debugger, you will be able to trace through your code
at any level of detail your require. Continuations are also supported, when a
<code>sendPageAndWait()</code> is invoked, the debugger will become inactive until the
interpreter is called upon to continue that suspended flow.
</p>
</s2>
</s1>
<s1 title="Improvements" >
<s2 title="Remote debugging">
<p>
Currently to use the flow debugger you really need to be working on
the same machine where your Cocoon application is running, either via a remote login
or locally on the system. The ability to remotely attach to a running system and debug
flow would be nice.
</p>
</s2>
<s2 title="Enable/disable without restart">
<p>
Currently to enable/disable the debugger one has to modify the
cocoon.xconf/flow.xconf files, perhaps it would be good if this was possible
dynamically, ie. without a restart of the servlet environment or Cocoon.
</p>
</s2>
</s1>
<s1 title="Comments">
<p>
Do you have an idea about how to improve the Cocoon flow debugger?
Please post it to the <link
href="mailto:[EMAIL PROTECTED]?subject=FlowDebugger:";>cocoon-dev</link>
mailing list. Care to comment on this How-To? Help keep this document relevant by
passing along any constructive feedback to the <link
href="mailto:[EMAIL PROTECTED]?subject=FlowDebugger:";>cocoon-docs</link>
mailing list.
</p>
</s1>
<s1 title="Revisions">
<p>
11-12-2002: Content originally submitted by Marcus Crafter.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
