MyBank

JCO

JWAA

Java+

ALE

Academia

Mideast

Cox

Installation

Documentation

Source

Changes

License

Demo

outerPages.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- The JWAA Outer Pages contain the website documentation; the pages
that must be accessible without going through the login portal. 
xmlns="http://www.w3.org/1999/xhtml"
xmlns:jwaa="http://virtualschool.edu/jwaa.dtd"
-->
<pages 
  title="JWAA Web Application Architecture"
>

<page id="OUTER" name="JWAA" requiresRole="none"
  title="Java Web Application Architecture (JWAA)"
>
  <child idref="INSTALLATION"/>
  <child idref="DOCUMENTATION"/>
  <child idref="SOURCE"/> 
  <child idref="CHANGES"/> 
  <child idref="LICENSE"/> 
  <child idref="PORTAL"/>

  <img align="right" src="/jwaa/pix/mvc.gif" alt="" width="117" height="114"/>

  <p>
    JWAA is a small but powerful architecture for writing web-based 
    applications in 
    <a idref="XHTML">XHTML</a>,
    <a idref="Velocity">Velocity</a> and <a idref="Java">Java</a>.
    JWAA is portable, <a idref="LICENSE">open source</a> (free) 
    code that is available for <a href="#download">download here</a>.
  </p>

  <p>
    JWAA features a fully object-oriented approach.  Applications 
    are networks of <i>page</i> objects that reference other pages 
    via standard object referencing semantics, not with text strings 
    buried in HTML text. JWAA brings the power of object-oriented 
    programming to bear on the web.
  </p>

  <br clear="all"/>

<h2>Reduced Navigation</h2>

  <p>
    JWAA represents pages as XML files, not as conventional HTML files.
    XML's well-known abilities as a general purpose data representation 
    language are used to express entire web applications in only a few 
    files.  For example, the JWAA website is defined by three XML files: 
    <a idref="application.xml">application.xml</a>,
    <a idref="outerPages.xml">outerPages.xml</a> and
    <a idref="innerPages.xml">innerPages.xml</a>.
    The number of files is determined your application.xml 
    file, not by HTML-imposed restrictions.
  </p>

<h2>Automatic reloading</h2>

  <p>
    JWAA monitors all input files for changes and automatically 
    reloads them when they change. Any errors are reported via 
    the browser when the XML file is first loaded, not buried 
    in an obscure log file.
  </p>

<h2>Invalid link detection</h2>

  <p>
    Invalid links are automatically detected and reported when each
    application is first loaded. The id of each page is automatically 
    recorded in a dictionary and can be referenced by idref attributes
    as described below.  The dictionary can be expanded to add links to 
    external pages via dictionary elements in the application.xml file.  
    Dictionary entries are referenced by providing idref attributes 
    to the usual &lt;a&gt; and &lt;img&gt; XHTML commands.
  </p>
    
<h2>Persistent forms</h2>

  <p>
    HTML lets you define forms that the user can type information into,
    but no way to store or process this information. That requires
    installing and learning languages, tools and environments that 
    bear no resemblance to HTML. The learning process is <i>discontinuous</i>.
  </p>

  <p>
    JWAA supports <a idref="FORMS">persistent forms</a> by default.  
    Like blackboards or paper, forms retain what the user writes 
    in them until it is explicitly changed or erased. Persistent forms 
    are a key building block for building form-based database-centric 
    applications such as wikis, quizzes, interview forms, and 
    so forth, often without any custom programming at all.  
    The default behavior is easily overridden.
  </p>
    
  <p>
    This feature was developed within the <a idref="ALE">Action Learning 
    Environment</a>, a JWAA application. It has been ported to JWAA on 
    as an experiment to investigate whether it makes sense to support
    persistent forms at a lower level.
  </p>

<h2>Self documenting</h2>

  <p>
    Other environments provide a bare foundation to build on from
    first principles.  JWAA provides a finished environment to live 
    in and learn from while you remodel it to suit. Building a new
    application is a matter of copying the application that provides
    this tutorial and changing it to suit, learning new skills as you go.
  </p>

<h2>Continuous learning</h2>

  <p>
    Ordinary HTML pages are static data files that are served 
    by a separate program such as Apache. That's fine until 
    the pages must support dynamic features when the learning 
    curve becomes discontinuous since new and unfamilar tools 
    must be installed and learned (perl or java, servlet 
    engines, etc).  
  </p>

  <p>
    JWAA provides a uniform and comprehensive XML-based environment 
    in which the transition from static to dynamic pages is continuous. 
    Simple static pages differ from advanced dynamic ones only in that 
    they don't use features that the same environment provides.
  </p>

<h2>Automatic session management via cookies and/or URL rewriting</h2>

  <p>
    If the browser supports cookies, JWAA uses them to support session
    management. Otherwise JWAA will automatically rewrite all URLs 
    so that session information is retained when the user clicks 
    a URL. The code that rewrites URLs is actually provided by 
    the servlet engine. JWAA's contribution is to guarantee that 
    all URLs are subject to URL-rewriting, even those that 
    are buried in hardcoded &lt;a href="..."&gt; strings.
  </p>

<h2>Integration <i>and</i> Separation of Concerns</h2>

  <p>
    JWAA supports both. When used with the 
    <a idref="Java+">Java+ preprocessor</a>, HTML is written as
    Java+ strings so that presentation and logic are combined
    and executable inclusions are expressed in plain Java. 
    The HTML can also be written as XML (XHTML) files and 
    automatically reloaded when they change, with executable 
    inclusions written in <a idref="Velocity">Velocity</a>.
    Since <a idref="Java+">Java+</a> now has its own web site, 
    this site will emphasize the XML-based approach.
  </p>

<h2>Consistent Look and Feel</h2>

  <p>
    Navigation bars, background colors, and headers/footer 
    information on this and all other pages in this website 
    constitute this application's look and feel.  The look 
    and feel is defined by <a idref="Velocity">Velocity</a> 
    macros such that the look and feel is centrally defined
    and easily changed.  These macros are, by default, 
    automatically reloaded when the file that defines
    them is changed.
  </p>

<h2>Model-View-Controller Paradigm plus Fields</h2>

  <p>
    JWAA pages are objects that supports a user's interaction with 
    internal objects, called Models (or JavaBeans). Model objects
    manage the application's persistent state, typically but not 
    necessarily as records in a database. By convention, model 
    objects' fields are not primitive Java datatypes like Strings. 
    Rather <b>fields</b> are the atoms from which models are composed.  
    Fields encapsulate the logic for validating user inputs, reporting 
    any problems by collaborating via the user interface. Fields are an 
    unusually powerful unit of reuse because they are tangible, concrete 
    and highly visible right in the application's user interface. 
    JWAA includes a comprehensive library of ready-to-use fields for
    building model objects in Java.
  </p>

<h2>Small, Fast, Secure</h2>

  <p>
    With Java+, applications are constructed entirely at compile
    time and are remarkably small. JWAA's core functionality (minus 
    documentation and demos) is only 67kb while JSP is many times 
    larger. No compilers are needed on deployment servers, so speed,
    space and security are substantially improved.
  </p>

<h2>Open Source</h2>

  <p>
    JWAA is <a idref="LICENSE">open source</a> (free) software, written 
    entirely in Java so it is automatically portable to any platform.
  </p>

<a name="download"></a>
<h2>Download Instructions</h2>

  <p>
    The JWAA distribution is <a href="/jwaa/jwaa.tgz">jwaa.tgz</a>.
    This is a gzipped tar file with the documentation, sources, compiled 
    binary, plus all required libraries except for four prerequisites
    that can be downloaded from the provided links.
  </p>
  
  <ul>
    <li>Web server (<a idref="Apache">Apache</a>)</li>
    <li>Relational Database (<a idref="MySQL">MySQL</a>)</li>
    <li>Java Software Development Kit (<a idref="Java">java.sun.com</a>)</li>
    <li>Servlet engine (<a idref="Jetty">Jetty</a> or <a idref="Tomcat">Tomcat</a>).</li>
  </ul>

  <p>
    See the <a idref="INSTALLATION">installation instructions</a>
    for how to proceed once you have the prerequisite software.
  </p>

<h2>JWAA Applications</h2>

  <p>
    <a idref="Mybank">Mybank</a> is an ambitious digital rights
    management system based on <a idref="JWAA">JWAA</a> and 
    <a idref="Java+">Java+</a>.  
  </p>
    
  <p>
    <a idref="ALE">ALE</a> (Action Learing Environment) pioneered the 
    XML-based approach that was subsequently absorbed into its JWAA 
    substrate.  
  </p>

  <p>
    <a idref="ILE">ILE</a> (Interactive Learning Environment) is
    an ancestor of ALE that involved porting JWAA from Java to Ruby.  
    This project is now inactive because a servlet engine problem 
    that surfaced during the move to a new collocation provider.
  </p>

</page>

<page id="DOCUMENTATION" name="Documentation" requiresRole="none"
title="Building web applications with JWAA" >
<child idref="APPLICATIONS"/>
<child idref="LOOKANDFEEL"/>
<child idref="FORMS"/>
<child idref="VELOCITY"/>
<child idref="JAVA"/>

<p>
  This documentation is divided into sections according to
  different levels of programming expertise:
</p>

  <ol>

    <li>
      <a idref="APPLICATIONS">Application Builders</a> write the 
      static HTML content of an application by authoring them
      in XHTML gathered into Jwaa's XML format.
    </li>

    <li>
      <a idref="LOOKANDFEEL">Look and Feel Specialists</a> 
      define the look and feel for an application by revising the Velocity 
      macros and CSS (Cascading Style Sheets) that are provided.
    </li>

    <li>
      <a idref="VELOCITY">Interaction Specialists</a>
      make pages interactive by adding statements in the Velocity 
      programming language.
    </li>

    <li>
      <a idref="JAVA">Java Programmers</a> 
      use this section for extending the Java backend of this system.
    </li>

  </ol>

</page>

<page id="APPLICATIONS" name="Applications" requiresRole="none"
  title="Building a new JWAA Application" >

  <p>
    JWAA is capable of running multiple applications simultaneously.  
    Each application is defined by its own sub-directory of the 
    jwaa/root directory. Each application directory is required to
    provide a <a idref="application.xml">application.xml</a> file
    that points to the other files that make up that application.
  </p>

<h2>The root/applicationName directory</h2>

  <p>
    For example, the pages you're reading now are provided by a JWAA
    application named "jwaa". This application is defined by the 
    root/jwaa directory. To build a new application, you simply 
    copy the root/jwaa directory to a new name and modify its contents 
    to be what you need. Don't change the jwaa directory.  Leave that 
    as it is to keep it is available for reference.
  </p>

  <p>
    The directory name determines the internal id of the application
    which determines the applicaton's URL. The first two components of 
    the url are defined by WEB-INF/web.xml as jwaa/xml. The third 
    component is application id, which is determined by the root 
    subdirectory name.  This tutorial is stored in root/jwaa, so the 
    tutorial application's id is jwaa.  Thus the jwaa tutorial's full
    URL is http://localhost/jwaa/xml/jwaa.
  </p>

  <p>
    These conventions are entirely governed by configuration files
    (typically etc/httpd/conf/httpd.conf and jwaa/WEB-INF/web.xml)
    so they can be easily changed according to the usual web server 
    and servlet engine conventions. To simplify this discussion, 
    these documents assume that the default settings are used.
  </p>

<h2>application.xml</h2>

  <p>
    Right click on <a idref="application.xml">this link</a> 
    to open jwaa/root/jwaa/application.xml in a new browser window. 
    Notice that it specifies other files in the application's root 
    directory. 
  </p>

  <p>
    Notice that application.xml specifies two pages elements 
    with the ids outer and inner. The path attribute of these 
    elements specify the two files that define the jwaa application,
    outerPages.xml and innerPages.xml.  This discussion will be 
    concerned with outerPages.xml which defines the pages
    you're reading now. The other involves interactive features 
    that will be described separately.
  </p>

  <p>
    Each application's directory is contains an 
    <a idref="application.xml">application.xml</a> file that 
    specifies where other application components are stored. Open 
    that file now (right click to open it in a separate browser window). 
    Notice that three lines at the top specify the files that define 
    the JWAA documentation and the tutorial demonstration application.
  </p>

  <p>
    The macros element specifies the name of the file that defines
    the velocity macros (we'll be concerned with these in the
    next section), and the role element(s) designate the login ids
    that are able to access special administrative pages that
    are invisible (and unreachable) by ordinary users. We'll 
    describe those after we cover how ordinary static HTML
    content pages are defined.
  </p>

<h2>Content Pages</h2>

  <p>
    Traditional pages are HTML files.  Jwaa pages, by contrast, are
    defined as elements inside XML files. Unlike HTML, each XML file
    file can define any number of pages.  The jwaa tutorial application 
    is defined by precisely two such files:
  </p>

  <ul>

    <li>
      <a idref="outerPages.xml">outerPages.xml</a> defines 
      the pages you're reading now. They are "outer" in the sense that they 
      lie outside of the demonstration application's login procedure.
    </li>

    <li>
      <a idref="innerPages.xml">innerPages.xml</a> defines 
      the pages of the demonstration application.  These are "inner" 
      in the sense that they cannot be accessed without registering 
      and logging in to the demonstration application. Most of these
      pages involve forms processing and will be described separately,
      under <a idref="FORMS">Forms Processing</a>.
    </li>

  </ul>

  <p>
    Which pages are defined in which files is arbitrary and entirely 
    up to the author's discretion. There is no significance to which 
    XML file a page is defined in. Page identifiers are maintained in 
    a single name space for each application, and the pages of that 
    application can reference each other freely, without concern for 
    which file they originated in.
  </p>

  <p>
    For example, open <a idref="outerPages.xml">outerPages.xml</a> 
    (right-click to open it in a separate window so you can continue
    reading these instructions).
    Notice that consists of a single large &lt;pages&gt;...&lt;/pages&gt; 
    (plural) element, that contains many &lt;page&gt;...&lt;/page&gt; 
    (singular) elements, each of which defines three attributes: 
  </p>

  <ul>

    <li>
      id: This is a string that will identifies the page to other pages.
      I recommend using uppercase identifiers to make them easy to find 
      with string searches.  
    </li>

    <li>
      name: This is the short name of the page as far as the end-user
      is concerned. It is visible in navigational menus, so keep it short 
      and meaningful.
    </li>

    <li>
      title: A longer string that will be presented at the top of each
      page as a &lt;h1&gt; header, and also as a title="" attribute in
      menu bars (which some browsers will present as a non-standard but
      useful rollover effect).
    </li>

  </ul>

  <p>
    The text within each page element is what'd normally goes in an 
    XHTML &lt;body&gt; element. The main difference is that they are 
    XHTML commands, not HTML commands.  They must comply with the 
    XHTML syntax requirements which are similar to HTML, but far 
    more strict. These differences are described <a idref="XHTML">here</a>.
  </p>

<h2>Building a new application</h2>

  <p>
    To build a new application, copy an existing one and modify it 
    to suit. So begin by copying jwaa/root/jwaa to jwaa/root/myapp. 
    In your browser's location bar, replace the second jwaa with myapp 
    and click reload.  There will be a short delay as Jwaa loads the XML 
    files into memory, the page you're reading now will appear.  
    Click reload and notice that the page reloads much faster.
    The JWAA servlet continually watches the root directory for 
    new arrivals, so new arrivals are automatically on the air.
  </p>

  <p>
    Open jwaa/root/myapp/outerPages.xml in your text editor
    and search for the string <code>id="APPLICATIONS"</code>, which
    defines the page you're reading now. Insert a word or two in the 
    first paragraph, save the file, and click reload.  Notice that 
    the change appears in your browser window after a much shorter delay
    since only one file had to be reloaded for this change.
  </p>

<h2>Correcting errors</h2>

  <p>
    The biggest difference between HTML and XHTML is that XHTML
    imposes strict syntax requirements. To see this in action,
    use your text editor to damage the file slightly (for example, by
    deleting the opening &lt;p&gt;). Save the result (but don't exit
    your text editor), and click reload in your browser. The browser 
    provides an error message pinpointing the error and requiring
    you to fix it.  Use your editor's undo function to repair
    the damage and reload the page in your browser to verify that
    the page now loads fine.
  </p>

<h2>Required Pages</h2>

  <p>
    The only requirement JWAA does impose is that each application
    must define certain pages that the hard-coded part of the system
    refers to. These required identifiers are:
  </p>

  <ol>

    <li>
      OuterHomePage: The outer home page for the application as a whole.</li>

    <li>
      InnerHomePage: The inner home page. The first page a visitor
      sees when they pass the login procedure.
    </li>

    <li>
      PortalPage: The login and registration initiation page.
    </li>

    <li>
      NotFoundPage: A page to be displayed if a requested page is not
      found, for example, if the user mistyped the URL.
    </li>

    <li>
      RefusePage: A page to be displayed if the user requests a page
      their role doesn't allow them to see.
    </li>

  </ol>

    <p>
      Workable versions of these pages are all defined in innerPages.xml
      and will not concern us further here.
    </p>

  <h2>Optimizing for Production</h2>

    <p>
    The outer pages of an application don't usually change very often
    after they've been tested and installed, certainly not compared to 
    inner pages that might be computed almost entirely on the fly. 
    Furthermore outer pages are typically the ones you want to be 
    picked up and cataloged by search engines, unlike the inner ones.
  </p>

  <p>
    There are no firm rules as to which pages should be served dynamically,
    via the JWAA/Jetty servlet engine, versus which should be served
    statically by a web server. The practice I follow is to periodically
    save the application's OuterHomePage (dynamically generated) into
    an index.html file in the application's root directory, and to have
    all other pages refer to this static page instead of its dynamic
    address.
  </p>

  <p>
    For example, the dynamic version of JWAA's own home page is
    http://virtualschool.edu/jwaa/index.html. This is the page that
    is picked up by search engines, and is served as a static web 
    page by the apache web server. The same page is also accessible
    as a dynamically generated page at 
    http://virtualschool.edu/jwaa/xml/jwaa/OuterHomePage. The static
    version (index.html) is derived from the dynamic version by
    simply using the browser's saveAs function to update the static
    version when the dynamic version changes.
  </p>

</page>

<page id="LOOKANDFEEL" name="Look And Feel" requiresRole="none"
title="Defining the application's Look and Feel"
>

  <p>
    An application's look and feel is governed by the velocity.macros 
    file in the top level directory
    of your application, plus any the CSS (Cascading Style Sheet)
    definitions that the macros use, which are typically stored in
    your application's css directory in the same location. 
  </p>

  <p>
    For example, see the \#defaultLogic() and \#header macros in
    <a idref="velocity.macros">velocity.macros</a>. 
    Controller automatically inserts calls to these at the
    beginning of each page's text and a call to the \#footer()
    macro at the end. Velocity simply replaces the call statements 
    with the text defined in the macros.
  </p>

  <p>
    Make experimental changes to these macros (keep them simple for
    now) and reload the browser to observe the effect. Then browse
    several pages and notice that changes to these macros have global 
    effects, automatically propagating to every page in your application.
  </p>

  <p>
    Notice that the \#header() macro includes a &lt;link command
    that tells the browser to load css/innerPage.css and
    css/print.css. These define additional page markup conventions
    that I also rely on to further adjust the application's look and
    feel. CSS markup is a separate topic that I'm still learning 
    myself. See the Reference list for more information on CSS.
  </p>

<h2>References</h2>

  <ol>

    <li>
      <a href="http://jakarta.apache.org/velocity/user-guide.html"> 
      Velocity User's Guide</a> is the most relevant.
    </li>

    <li>
      <a href="http://www.w3schools.com/css/default.asp">CSS 
      Tutorial</a> by W3Schools.
      </li>

  </ol>

</page>

<page id="FORMS" name="Forms" requiresRole="none"
  title="Persistent Forms" >

  <p>
    Forms are defined with the usual XHTML form, input and select
    statements... with important differences stemming from the
    need to not only define the form presentation (as in XHTML),
    but also logic for processing that form once submitted.
  </p>

  <p>
    Persistent form support is under development and rapidly changing.  
    I'll upgrade this documentation as the design stabilizes.  See the 
    PORTAL and UPDATE pages of <a idref="innerPages.xml">innerPages.xml</a> 
    for how to code forms in the traditional (manual) way within JWAA.
  </p>

<h2>Persistent Form Example</h2>

  <p>
    See the FORMS element in <a idref="outerPages.xml">outerPages.xml</a>
    for this test case for the persistent forms feature.
  </p>

  <form id="DEMO_FORM">
    <logic>
#set($op = $form.getValue("op"))
#if ($op)
    $form.save()
    #if ($op eq "Prev")
      $self.gotoPage($self.getPrevPage().getId())
    #elseif ($op eq "Next")
      $self.gotoPage($self.getNextPage().getId())
    #end
#end
    </logic>

    <table align="center">
      <tr>
        <td>Text Fields </td>
        <td>
          <input name="textField" type="text" />
        </td>
      </tr>
      <tr>
        <td>Password Fields </td>
        <td>
          <input name="passwordField" type="password" />
        </td>
      </tr>
      <tr>
        <td>Radio Selection Fields </td>
        <td>
          <input name="radioFieldName" value="Yes" type="radio"/> Yes
          <input name="radioFieldName" value="No" type="radio"/> No
          <input name="radioFieldName" value="Maybe" type="radio"/> Maybe
        </td>
      </tr>
      <tr>
        <td>Checkbox Fields </td>
        <td>
          <input name="checkboxField" value="Yes" type="checkbox"/> Yes
          <input name="checkboxField" value="No" type="checkbox"/> No
          <input name="checkboxField" value="Maybe" type="checkbox"/> Maybe
        </td>
      </tr>
      <tr>
        <td>Single Selection Fields</td>
        <td>
          <select name="singleSelectionField">
            <option>Yes</option>
            <option>No</option>
            <option>Maybe</option>
          </select>
        </td>
      </tr>
      <tr>
        <td>Multiple Selection Fields </td>
        <td>
          <select name="multipleSelectionField" multiple="multiple">
            <option>Yes</option>
            <option>No</option>
            <option>Maybe</option>
          </select>
        </td>
      </tr>
      <tr>
        <td> Text Area Fields </td>
        <td>
          <textarea name="textareaField" rows="2" cols="15"></textarea>
        </td>
      </tr>
      <tr>
        <td>Submit Buttons </td>
        <td>
          <input name="op" value="Prev" type="submit"/>
          <input name="op" value="Save" type="submit"/>
          <input name="op" value="Next" type="submit"/>
        </td>
      </tr>
    </table>

  </form>

  <p>
    To try it, change the field contents, click one of the Submit 
    buttons and notice that the changes persist when you return,
    just as the information on paper remains when you look at it later. 
  </p>

  <p>
    If the server is heavily loaded, what you see depends on 
    whether you've logged (via the <a idref="PORTAL">Demo login screen</a>).  
    Visitors who haven't logged in share the same account and 
    their modifications to persistent forms affect the same
    database records, so persistent form contents will be as 
    the last visitor set them.  So if you're not logged in, 
    persistent forms behaves like blackboards that can be 
    read, written on, or erased by anyone that walks by. 
    If you have logged in, forms behave like paper that is
    under your sole control.  We assume both cases are 
    potentially useful.
  </p>

  <p>
    The contents of each field persist as records in a relational 
    database (MySQL) keyed with the page id, the field name, and
    the user's ID. Users who have not logged in via the 
    <a idref="PORTAL">Demo login screen</a> share the same account
    and have concurrent access to the same database fields.  JWAA
    does not prevent such users from overwriting each other's work
    on the grounds that blackboards and paper have the same liability
    but are still useful in education.
  </p>

  <p>
    The persistence feature applies only to form elements that
    do <i>not</i> define explicit values. It does not apply
    to text or password fields with value attributes, to checkbox,
    radio, and select fields with checked attributes and so forth).
    It can be turned off in forms that should not be persistent 
    (login screens and so forth) by simply defining explicit values.
  </p>

<h2>Unresolved Issues</h2>

  <p>
    I'm eager to support persistence at the lowest architectural 
    level because persistent forms are such a powerful unit of 
    reuse... for exactly the same reasons that paper and blackboards
    are so useful in education. They are lowest-level building blocks 
    that support many concrete interactive applications. I've 
    supported them experimentally to validate the truth of this
    claim in practice.
  </p>

  <p>
    By contrast, <a idref="ALE">ALE</a> provides workflow features 
    that model the paper workflow in classrooms. The instructor develops
    quizzes and passes them to students, who write answers on them and 
    return them to the teacher, who grades them and returns them to students
    to read the teacher's feedback.  ALE's support for such workflow 
    has not been ported to JWAA because that is clearly inappropriate
    at JWAA's level.  
  </p>

  <p>
    I'm not sure of where to draw this boundary. So the persistent
    forms feature has been added provisionally. The goal is to 
    investigate whether persistent forms belong at the JWAA level 
    in the absence of ALE's workflow support. If not, I'll 
    remove it from JWAA and support it only within ALE.
  </p>

  <p>
    I'm not entirely satisfied with how navigational controls (the Prev,
    Save, and Next buttons in this example) are handled. ALE provides 
    these automatically and consistently as part of its workflow 
    support, so no effort is needed to present them everywhere they 
    are needed.  This can't be done at JWAA's level since the default 
    navigational controls would clash with the user's page design.
  </p>

  <p>
    I welcome other opinions on these issues.  Share them via email with
    <a href="mailto:bcox@virtualschool.edu">bcox@virtualschool.edu</a>.
  </p>

</page>

<page id="VELOCITY" name="Velocity" requiresRole="none"
  title="Programming with Velocity">

  <p>
    Velocity is a language for accessing objects provided
    to it by the Java part of the system. The following objects 
    are automatically available to velocity code via velocity's
    "context".  For further information see the 
    <a idref="ObjectReferenceManual">ObjectReferenceManual</a>.
  </p>

  <dl>

    <dt>\$self</dt>

    <dd>
      \$self provides access to the <a idref="Controller">Controller</a>
      for the page that is currently being displayed. The controller 
      provides methods that velocity scripts use to access other objects 
      in the page's neighborhood, such as 
      the <a idref="PageElement">PageElement</a> that defines this page,
      the <a idref="PagesElement">PagesElement</a> in which this page
      was defined, 
      the page's <a idref="ApplicationElement">ApplicationElement</a>, 
      and more. 
    </dd>

    <dt>\$account</dt>

    <dd>
      \$account provides access to information about the account
      that is currently logged in. From this you can determine
      their name, address, phone number, and similar information 
      from the registration procedure.
    </dd>

    <dt>\$dbms</dt>

    <dd>
      Each application maintains a pool of connections to the
      application's database as a <a idref="DBPool">DBPool</a> 
      instance. The controller automatically withdraws a database 
      connection (a <a idref="DB">DB</a> instance) from the pool 
      and makes that instance available to velocity code as the 
      $dbms context variable. 
    </dd>
      
    <dd>
      Your code can use this variable to access the database by 
      calling the public methods that DB provides for this purpose. 
      The controller automatically either commits any transactions 
      that finish successfully (and rolls back those those that 
      fail; i.e. those that throw exceptions). Finally it returns
      the DB instance to the pool for reuse.
    </dd>

    <dt>$form</dt>

    <dd>
      The $form variable is null if the page contains no &lt;form&gt;
      element and an instance of <a idref="FormElement">FormElement</a>
      if it does. This may change in future releases such that form
      elements can be accessed via the \$self or \$self.page variables.
    </dd>

  </dl>

<h2>Velocity Hints</h2>

  <p>
    Velocity statements like \$self.application don't access 
    the Controller's "application" field directly. Velocity 
    automatically treats such statements as if written
    \$self.getApplication(), which calls the Controller's 
    getApplication() method to return the value.  In other 
    words, fields are never accessed by Velocity code, 
    only methods, and then only those methods that 
    are explicitly public.
  </p>

  <p>
    But always remember that methods are general-purpose functions
    that can (and often do) make permanent changes to their environment.
    Such methods are said to have <i>side-effects</i>. This is actually
    quite useful, for it is how velocity scripts affect their environment.
  </p>

</page>


<page id="JAVA" name="Java" requiresRole="none" title="Java Programmer's Guide" >
  <child idref="OVERVIEW" />
  <child idref="MODELS" />
  <child idref="FIELDS" />
  <child idref="ROLES" />

<p>
  Simple JWAA websites can be built entirely in XML and Velocity, without 
  exploring the Java end of this system more deeply than reading the
  <a idref="ObjectReferenceManual">ObjectReferenceManual</a> for Java 
  class descriptions.  However the Java source code must be documented 
  for those who wish to explore it.  And some things, such as extending 
  the system with new persistent objects, are only really practical in 
  Java.
</p>

<h2>Prerequisites</h2>

<p>
  Begin by downloading and installing the following tools from the
  specified links:
</p>

<ol>

  <li>
    <a idref="Eclipse">Eclipse</a>: Eclipse is the main tool for
    reading Java source code, making changes, correcting mistakes,
    compiling source code to executable class files, debugging 
    running programs, and viewing data structures 
    while the program is running. The best version to download
    is version 2.1.1: the later "milestone" versions are too 
    buggy to count on in my experience. Also avoid plugins:
    they are even more problematic than eclipse.
  </li>

  <li>
    <a idref="Ant">Ant</a>: Ant is a command line tool that is
    used for everything Eclipse doesn't do: compiling documentation
    from source code (via doxygen), building jar files from 
    individual class files, copying files from the build directory
    to the deployment directory, maintaining backup copies, 
    building distribution (.tgz) files, and so forth. 
  </li>

</ol>

<p>
  Install ant and eclipse where ever you please (I use /opt)
  and make scripts to launch them conveniently. Here's the script 
  I use for launching eclipse (the Fixme comment marks
  two lines to edit to suit your system).
</p>

<pre>
#!/bin/sh

# Fixme
ECLIPSE_DIR=/opt/eclipse-2.1.1
WORKSPACE_DIR=~/workspace

# Launch eclipse
cd $WORKSPACE_DIR
$ECLIPSE_DIR/eclipse -data $WORKSPACE_DIR $* &amp;
echo $ECLIPSE_DIR starting ... 
</pre>

<p>
  The WORKSPACE_DIR line overrides eclipse's annoying behavior
  of creating a default workspace inside eclipse's program 
  directory. "Workspace" in eclipse's term for the directory
  that it uses to store <b>your</b> source code. Its not eclipse's
  code, its <b>yours</b>, and you want to control where its stored
  rather than leaving that up to eclipse. My preference is for the
  workspace to be in my home directory which is where the default
  settings in the above script puts it.
</p>

<h2>Importing JWAA into Eclipse</h2>

<p>
  Launch eclipse, pull down the Window menu, and choose 
  Preferences. Click the triangle by Java in the left panel
  to open it, click Compiler, and select the "Folders" option
  under "Source and output folder". Leave the default source
  folder name ("src") and output folder name ("bin") as they
  are.  Click "OK". Eclipse will now create new projects with 
  src and bin folders, which matches the convention I'll use in 
  this document.
</p>

<p>
  Right click in the left panel (Package Explorer) and click
  "New Project". Choose "Java" in the popup panel and click Next.
  Type "JWAA" as the project name and click Finish. JWAA will now
  appear in the left panel as a new but empty project.
</p>

<p>
  Right click on the JWAA project in the left pane and choose
  Import. Browse to the installed copy of JWAA, double-click it
  and JWAA should appear in the left pane with an empty checkbox.
  Eclipse is somewhat unreliable here; often the left pane doesn't
  change when you select a directory. Clicking the back button and
  advancing with the Next button appears to resolve it. Once JWAA
  appears in the left panel with the empty checkbox, click the 
  checkbox to select it and click finish. A red checkbox signifying
  compile errors will appear in the left panel. The errors are OK:
  you haven't defined libraries yet.
</p>

<p>
  Right-click on the imported project and choose Properties. In the
  left panel of the window that appears, click "Java Build Path".
  Select the Libraries pane and click "Add Jars". Click JWAA,
  then WEB-INF, then lib, and drag-select all of the jar files 
  that are offered there. Click OK. A few errors will remain
  because you've not provided the servlet engine's libraries yet.
</p>

<h2>Importing Jetty into Eclipse</h2>

<p>
  Repeat all of the above steps to import Jetty into a separate
  "Jetty" project in your workspace. Use "Add Jars" in the Jetty
  project until Jetty compiles without errors. Right-click on your 
  JWAA project, choose Properties again, and this time select the
  "Projects" tab. Checkboxes for the JWAA and Jetty projects should
  appear there. Select the checkbox next to the Jetty project to
  specifies that Eclipse should use the bin directory of the Jetty
  project to resolve unsatisfied references in addition to the jar
  files you specified earlier.  JWAA should build now without errors 
  and the red mark in the left pane will disappear.
</p>

<p>
  Recall that Jetty refers to symbolic links (or outright copies)
  in its webapps subdirectory to determine which servlets it should
  load, and it expects each such link (or copy) to contain a WEB-INF
  directory.  When Eclipse copied Jetty to its workspace, it copied 
  Jetty's webapps directory along with the symbolic link you made earlier.
  This link points to the original copy of JWAA in the document root 
  directory. You want this copy of Jetty to load files from the
  copy of JWAA in your workspace. So delete the jwaa copy and replace 
  it with a new symbolic link to the JWAA in your workspace 
  directory, like this:
</p>

<pre>
cd ~/workspace/Jetty/webapps
# notice the old jwaa copy
ls -l                         
# remove the old jwaa copy
rm -rf jwaa                   
# create a symbolic link to workspace/jwaa
ln -s ~/workspace/jwaa/ jwaa  
</pre>

<p>
  Jetty will load jar files from the WEB-INF/lib directory and 
  individual class files from the WEB-INF/classes directory.
  The WEB-INF/lib directory already contains a copy of the 
  jwaa.jar that came with the distribution. Since you'll be
  making changes to the jwaa source code, you want the changed
  versions to be loaded, not the original distributed version.
  The simplest way to ensure this is to create a symbolic link,
  named classes, in the WEB-INF directory that points to the
  bin directory in which Eclipse stores its generated files,
  like this:
</p>

<pre>
cd ~/workspace/jwaa/WEB-INF
ln -s ../bin classes
</pre>

<h2>Launching Jetty from inside Eclipse</h2>

<p>
  Back to Eclipse now. Pull down the Run menu, choose
  Debug, and a window will appear. Under Main, in the
  Project area, click the Browse button and select the 
  Jetty project. In the "Main class" area, choose Search,
  and select org.mortbay.start.Main as the main routine
  Eclipse should invoke to launch Jetty.
</p>

<p>
  In the Arguments tab, type the full path to the jetty.xml
  file in Jetty's etc directory. This is 
  /home/bcox/workspace/jetty/etc/jetty.xml in my case.
</p>

<p>
  In the Classpath tab, use Add Jars to add all of the jars
  in Jetty's lib directory. Then use Add Projects to add
  all of the projects that you'll be working with, just jwaa
  in this case. 
</p>

<p>
  Finally, click Apply, then Debug. Jetty should launch 
  without errors and display its normal startup dialog 
  in the console window at the bottom of the screen. 
  If any errors are displayed, it is probably because these
  instructions missed a required jar. Another common problem
  is trying to run muliple copies of jetty, which won't work.
  You must shut down any external copies for the new one
  to launch.
</p>

<p>
  Jetty is now running within Eclipse, and JWAA is running as
  a servlet within Jetty, and all facilities of both are accessible
  to the Eclipse debugger. Confirm that JWAA is accessible within
  Jetty by opening a browser window on http://localhost/jwaa and
  confirming that browsing to subpages work as before.
</p>

<p>
  Now let's set a breakpoint. In the Java Source browser (click the
  J icon on the left edge, open the jwaa project (click the triangle),
  open its src folder, and open the edu.virtualschool.jwaa.xml folder.
  Double-click on Controller.java and view the source code in the middle 
  pane. In the right pane, click on the run() method, which is the
  code that services each page request. Find the line that reads
  "send(evalText)" near the end of this method, and double-click in
  the blue margin next to this method. A blue dot will appear, signifying
  that a breakpoint has been set on this statement. 
</p>

<p>
  In your browser, click any link to request a new page. Eclipse will
  switch automatically to its Debug view with the selected statement
  highlighted in a smaller source window. The window above that will
  show a backtrace of the method calls that led to this point. Click
  on these and observe that the source code shown in the bottom window
  changes to show the clicked method. Click on the run method again
  and notice that all variables that were scope at the point of the 
  breakpoint is available for browsing. For example, pageText shows
  the XML code for the selected page before it was processed by
  velocity, and evalText shows the text as processed by velocity
  just before the send() method sends it to the browser.
</p>

<p>
  In other words, every aspect of the program is exposed to view
  and subject to modification: not just the source code but the
  actual run-time data while the code is running. It can't be
  any easier than that!
</p>

</page>

<page id="OVERVIEW" name="Overview" requiresRole="none" 
  title="Overview of the Java side of this system" >

<p>
  See the <a idref="ObjectReferenceManual">ObjectReferenceManual</a> 
  for Java class descriptions.  This section provides an overview of 
  and suggestions for modifing and extending these classes.
</p>

<h2>Startup-time Processing</h2>

<p>
  JWAA's main entry point is the init() method of 
  <a idref="JwaaServlet">JwaaServlet</a>, a subclass of 
  <a idref="GenericServlet">GenericServlet</a> from which it 
  inherits most of its methods.
</p>

<p>
  The JwaaServlet constructor initializes a dispatch
  table with a list of <a idref="MetaPage">MetaPage</a> 
  instances, one for each GenericServlet instance in the system. 
  With Java+, each page is an instance of Page and each defines 
  a MetaPage as a reference point for other pages to use when 
  emitting links to that page. When the XML feature of JWAA is 
  used, this table contains only a single instance; an instance of 
  <a idref="Controller">Controller</a> that is shared by all pages.  
  This instance serves as the controller for all JWAA pages, 
  dispatching requests in a manner similar to the usual JWAA 
  dispatching machinery, but based on the id defined for each
  page in the XML files.
</p>

<p>
  The init method retrieves several init parameters defined in
  the jwaa/WEB-INF/web.xml file and that locate the other parts
  of the system:
</p>

<ul>

  <li>
    url.prefix: This makes the application aware the URL prefix string. 
    This parameter should be hand-constructed by concatenating the 
    servlet name and url pattern (defined elsewhere in this file).
    By default, the servlet name is /jwaa and the url pattern is /xml/*,
    so the url.prefix is /jwaa/xml. Like all settings in this file,
    this can be changed if desired.
  </li>

  <li>
    home.directory: The absolute path to jwaa's installation directory.
    By default, this refers to a symbolic link in the system root
    directory, /jwaa, that points to the real installation directory.
  </li>

  <li>
    root.directory: The absolute path to jwaa's root directory.
    By default, /jwaa/root.
  </li>

  <li>
    properties.directory: The absolute path to the directory the
    class loader will load properties files from. By default,
    /jwaa/WEB-INF/classes.
  </li>

</ul>

<p>
  The init() method passes root.directory as an argument to
  the <a idref="RootDirectory">RootDirectory</a> class's constructor. Each 
  subdirectory of the jwaa/root directory is required to contain an
  application.xml file that locates any other files used
  by that application. The application.xml files are
  not loaded at init time. It and the files it refers to 
  are loaded when they are first referenced so that any 
  errors can be reported via the browser, not hidden in 
  log files.
</p>

<h2>Load-time Processing</h2>

<p>
  The directory names in jwaa/root determine the id's for
  each application. Browser requests are of the form
  /jwaa/xml/applicationID/pageID.  The JwaaServlet doRequest
  method (inherited from GenericServlet) uses the /jwaa/xml 
  component as the key for a dispatch table lookup, which
  selects the (sole) dispatch table entry for Controller.
  If the search fails, the search returns 
  JwaaServlet.getDefaultPage(), which specifies the same
  class, so the MetaPage entry for Controller has no real
  signficance.
</p>

<p>
  The doRequest() method creates an instance of Controller
  calls that instance's init() method to initialize
  the instance with the MetaPage instance, servlet, 
  HttpRequest and HttpResponse, and calls the instance's
  run() method to handle the request.
</p>

<p>
  The instance's run method retrieves the servlet from its init 
  parameters and calls its getRoot() method to retrieve the root 
  object for that servlet. The rest of the request string
  (/applicationID/pageID) is passed to the root's findPath()
  method to determine the application and the page within
  that application. If the application is not found, an error
  is reported.
</p>

<p>
  XML loading is triggered from within the root object's findPath() 
  method. The <a idref="RootDirectory">RootDirectory</a> class maintains a HashMap
  of the application instances that it built when it last scanned
  the root directory and a <a idref="FileField">FileField</a>
  instance that records the root directory's path and last modification 
  time. If the current modtime is greater than the last modtime,
  the directory is rescanned, ensuring that new applicaions will be 
  noticed and added to the HashMap.
</p>

<p>
  The HashMap entries are instances of <a idref="ApplicationElement">ApplicationElement</a>
  each of which maintains the information specified in a specific application.xml
  file along, a FileField that records when that file was last changed, 
  and a list of <a idref="PagesElement">PagesElement</a> instances, one for each pages
  element in that file.  The FileField is examined each time that 
  instance's update() method is called. If the FileField is out of date, 
  Otherwise, the file is reloaded to pick up any changes. Either way, the
  update() request is conveyed to each PagesElement instance.
</p>

<p>
  Each PagesElement instance also maintains a FileField for its XML file
  and a list of the Page instances specified in that file. If the
  FileField is up to date, the update() request returns immediately.
  Otherwise the file is reloaded and the list of Page instances is
  rebuilt.
</p>

<p>
  XML file loading at all levels involves using JDOM in the usual
  manner to populate instance variables with the information conveyed
  in the file.
</p>

<h2>Dispatch-time Processing</h2>

<p>
  Jetty calls JwaaServlet's (inherited) doRequest() method for
  each URL request that makes its way to the servlet engine from
  Apache. This includes only those that match the servlet-name
  and url-mapping defined in web.xml; all others are by 
  definition intercepted by Apache.
</p>

<p>
  The doRequest() method calls request.getRequestURI() to
  obtain the request URI from the request parameters. This is
  looked up in the (empty) dispatch table, which always fails, so
  JwaaServlet's getDefaultPage() method is called which always
  returns the metapage of Controller. JwaaServlet constructs an 
  instance of Controller and initializes it with the Controller's 
  metapage, the JwaaServlet instance, and the request/response 
  parameter objects). Finally the Controller's run method is called 
  to service the request.
</p>

<h2>Controller</h2>

<p>
  Controller is the primary interface between the
  Java and Velocity sides of the system. It holds the execution
  state that governs communication with the browser
  (request/response and servlet parameters) and links to the page
  being served in this transaction. The page instance in turn
  references its container, a pages instance, which in turn
  references its parent, and so on, until the parent links
  converge on the application and thereby the parent of all applications,
  the RootDirectory object. In other words, the page instance can be
  traversed (via methods the Controller provides to make this
  convenient) to reach the other objects in the system.
</p>

<p>
  The Controller processes each request by passing the
  pathInfo string to the getPath() method of the RootDirectory instance,
  expecting a page instance in return. The RootDirectory instance breaks
  each request into (up to) three slash-separated identifiers;
  application, pages, and page. The application id specifies a
  application, the pages id is looked up in its pagesMap to
  determine a PagesElement instance, and the page id is looked
  up in its pageMap to determine the Page instance. If all three
  lookups succeed, the resulting Page instance is returned, else
  various shorthands and defaults are employed to ensure that a
  valid Page instance is always returned (although not 
  necessarily the one that the user requested).
</p>

<h2>XML Loading/Reloading</h2>

<p>
  RootDirectory's getPath() method calls its update() method which
  handles loading of XML pages and reloading them when they are
  changed. Only four JWAA classes manage files directly: RootDirectory
  (which monitors application directory names, not files), 
  <a idref="ApplicationElement">ApplicationElement</a>
  <a idref="PagesElement">PagesElement</a> and 
  <a idref="PageElement">PageElement</a>.
  All others are derived from elements of the
  above files. These four classes each maintain a FileField
  instance that contains the path to the file and the last
  modification time of that file. Each update() compares this
  with the file's current modtime and reloads that object from 
  XML if the current modtime is greater than the stored one.
</p>

<p>
  The XML loading process is straightforward. The XML parsing
  involves using JDOM and the libraries that support it to
  parameterize constuctors for each of the Java model classes
  from XML attributes. The Page class's constructor walks the
  element tree completely, rewriting JDOM's question-and-answer
  elements into Velocity macro calls, then call's JDOM's
  Outputter class to convert its DOM tree to an ordinary string,
  which is mainted thereafter in an instance variable. No XML
  parsing occurs thereafter; its all done once when JWAA first 
  notices the file has changed.
</p>

<h2>Permission Checking</h2>

<p>
  Once the Controller receives a Page instance from the RootDirectory
  lookup process, it compares the pages requiredCapability
  instance variable (it is set in the XML file) with the
  capabilities of the account requesting that page. If the account
  has the required capability, the access is allowed. Otherwise
  the page is replaced with the application's refuse page. (as
  shipped, JWAA's refuse page silently forwards the user to the
  login page, which I find less offensive than the usual "access 
  refused" alert and has much the same effect.)
</p>

<h2>Database Access</h2>

<p>
  The Controller initializes an instance variable with a JDBC
  database connection from the connection pool (inside a try
  block with a finally clause to return it to the pool when
  finished with it). Then it uses that connection to initialize
  two HashMap variables, answerMap and reviewMap, with the
  answers to each question asked on that page, and the reviews of
  each answer, for the convience of the velocity macros that 
  present questions, answers, and reviews to the student.
</p>

<h2>Velocity Context</h2>

<p>
  The Controller builds an instance of VelocityContext for
  each request and initializes it with (1) \$self: the Controller
  instance, (2) \$account: the account that is currently logged
  in, and (3) any form parameters.
</p>

<h2>Velocity Dispatching</h2>

<p>
  Finally the page's text is retrieved from the Page instance
  and passed (with the context object) to an instance of
  VelocityEngine. Each application manages separate VelocityEngine
  instances so that each can have its own directory, 
  velocity.macros files, and so forth.
</p>

<p>
  The VelocityEngine essentially transforms the string passed
  to it by processing velocity commands embedded therein against
  the context information according to well-defined rules,
  returning a new string as the result. The Controller simply
  sends this string to the browser as (X)HTML text where it gets 
  handled as usual.
</p>

<h2>Database (Bean or Model) Objects</h2>

<p>
  The JWAA demo uses a single persistent object,
  <a idref="DemoAccountBean">DemoAccountBean</a>, which manages account
  information in a single table, Account, in the
  JWAA database.  Each row manages the name and address
  information of a specific user. This table is populated by
  the login/registration process and modifed thereafter 
  by the account update service.  
</p>

</page>

<page id="MODELS" name="Models" requiresRole="none"
  title="Models are an application's persistent memory" >

<p>
  Model (aka "Bean") classes manage an application's data 
  as database tables. The demo's model class is <a
    idref="DemoAccountBean">DemoAccountBean</a>.  
  <i>Fields are to models as atoms are to molecules.</i>. This 
  means that models are not defined in terms of raw Java types 
  such as Strings. Rather the models' instance variables and method
  arguments are declared in terms of objects that abide by the
  <a idref="Validatable">Validatable</a> interface. Since Validatable objects are
  typically implemented as subclasses of <a idref="GenericField">GenericField</a>, 
  they are called <i>Field</i> classes.
</p>

</page>

<page id="FIELDS" name="Fields" requiresRole="none"
  title="Fields are the atoms; models the molecules" >

  <p>
    Models are made of Fields not Strings. Strings are avoided 
      because:
  </p>

<ul>

  <li>
    Fields are uniquely reusable units of reuse because they
    are so concrete, immediately tangible and visible to everyone 
    in the application's user interface
  </li>

  <li>
    Fields encapsulate the rules for determining whether
    user-provided inputs comply with the syntactical validity
    constraints of that field. Centralizing this logic in
    reusable field classes makes applications much simpler than
    the traditional approach of distributing this logic 
    throughout the application.
  </li>

  <li>
    Each field can enforce DBMS-specific constraints, such as 
    the maximum length of fixed-length fields.
  </li>

</ul>

<p>
  The JWAA package provides a <a idref="Validatable">Validatable</a> interface,
  which defines the protocol that all field implementations
  adhere to. It also provides an abstract <a idref="GenericField">GenericField</a> that 
  defines methods for subclasses to inherit.
</p>

<p>
  Typically you'd define your database to use the field
  lengths specified by these classes. If not you should edit the
  classes to match. Only U.S. address and phone numbers are
  provided. Revisions to support international usage would 
  be gratefully accepted.
</p>

</page>

<page id="ROLES" name="Roles" requiresRole="none"
title="Roles determine who can see what pages" >

<p>
  Since each application is likely to have unique requirements
  for determining who is allowed to access each page, JWAA
  capability system is extendible. The demonstration uses the 
  simple three-level role system defined in 
  <a idref="GenericRole">GenericRole</a> and
  <a idref="RoleAbstraction">RoleAbstraction</a>.
</p>

<ul>

  <li>
    Visitor: for visitors whose identity is unknown because 
    they've not registered and logged on.
  </li>

  <li>
    Registered: for visitors that have registered and logged on.
  </li>

  <li>
    Admin: a privileged account permitted to access 
    administrative functions.
  </li>

</ul>

<p>
  The pages of a web application can be thought of as an outer 
  lobby with pages that everyone is welcome to read (logged in or not)
  plus an inner sanctum with pages that can only be accessed by those 
  who have logged in. The "portal" is the passage between them; the 
  guard station through which visitors pass to be identified by 
  the login procedure.  
</p>

<p>
  The demo application's inner sanctum consists of only three pages 
  to keep the demo as simple as possible: <a idref="UPDATE">UPDATE</a> 
  supports editing an account's registration information, 
  <a idref="LOGOUT">LOGOUT</a>, supports logging out, and 
  <a idref="ADMIN">ADMIN</a> lets administrative users view the database.
</p>

<p>
  <a idref="PORTAL">PORTAL</a> is the doorway between the two regions.
  If a visitor has not logged in, they browse as the account 
  AccountAbstraction.Null, the account for unknown visitors.
</p>

<p>
  When the visitor identifies themselves to the login
  procedure (in the demo, by providing a previously registered
  email address, but more typically, by also providing the
  corresponding password), <a idref="PORTAL">PORTAL</a> loads the account's
  persistent information from the database as an instance of
  <a idref="AccountAbstraction">AccountAbstraction</a> and stores a reference to this
  instance as a specially named session attribute. The session
  attribute persists as the user browses from page to page. It
  will only be erased by the LogoutPage, if the session times 
  out, or if the server itself is restarted.
</p>

<p>
  Notice that <a idref="DemoAccountBean">DemoAccountBean</a> implements the
  <a idref="AccountAbstraction">AccountAbstraction</a> interface, which requires that all
  subclasses provide a isCapable(Capability c) method. The system
  calls this method to determine if a given account has the 
  capability level in the method's argument.
</p>

<ul>

  <li>
    <a idref="LOOKANDFEEL">LookAndFeel</a> will refuse to show links to that
    page in the navigation bar. This lets the page hierarchy,
    which governs the navigation bar, be specified without
    concern for account capabilities, since the navigation bar
    will offer only the links that the viewer is allowed to 
    access.
  </li>

  <li>
    <a idref="GenericServlet">GenericServlet</a> redirects requests from viewers
    with inadequate capabilities by redirecting them to the page
    specified by the servlet's getRefusePage() method. This is a
    second line of defense to ensure that unauthorized visitors 
    can't bypass the protection by editing requests by hand.
  </li>

</ul>

</page>

<page id="LICENSE" name="License" requiresRole="none"
  title="JWAA Open Source License" >

<h2><a href="http://www.opensource.org">Open Source</a> Artistic License</h2>

<p>
  This states the conditions under which JWAA may be copied,
    such that the Copyright Holder maintains artistic control over 
    its development while giving its users the right to use and 
    distribute the Package and the right to make reasonable modifications.
</p>

<h2>Definitions:</h2>

<ul>

  <li>
    "Package" refers to the collection of files distributed by
    the Copyright Holder as the 

    <a idref="JWAA">Java Web Application Architecture (JWAA)</a> and 
    derivatives of that collection created through textual modification.
  </li>

  <li>
    "Copyright Holder" is Brad J. Cox, Ph.D., 9940 Bent Tree

        Lane, Manassas VA 20111.
    </li>

    <li>
      "Standard Version" refers to such a Package if it has not
    been modified, or has been modified in accordance with the

    wishes of the Copyright Holder.
  </li>

  <li>
    "You" is you, if you're thinking about copying or

        distributing this Package.
    </li>

    <li>
      "Reasonable copying fee" is whatever you can justify on the
    basis of media cost, duplication charges, time of people
    involved, and so on. (You will not be required to justify it to
    the Copyright Holder, but only to the computing community at

    large as a market that must bear the fee.)
  </li>

  <li>
    "Freely Available" means that no fee is charged for the
    item itself, though there may be fees involved in handling the
    item. It also means that recipients of the item may
    redistribute it under the same conditions they received

    it.
  </li>

</ul>

<h2>Terms</h2>

<p>
  1. You may make and give away verbatim copies of the source
  form of the Standard Version of this Package without restriction,
  provided that you duplicate all of the original copyright notices

  and associated disclaimers.
</p>

<p>
  2. You may apply bug fixes, portability fixes and other
  modifications derived from the Public Domain or from the
  Copyright Holder. A Package modified in such a way shall still be

  considered the Standard Version.
</p>

<p>
  3. You may otherwise modify your copy of this Package in any
  way, provided that you insert a prominent notice in each changed
  file stating how and when you changed that file, and provided

  that you do at least ONE of the following:
</p>

<ul>

  <li>
    place your modifications in the Public Domain or otherwise
    make them Freely Available, such as by posting said
    modifications to Usenet or an equivalent medium, or placing the
    modifications on a major archive site such as ftp.uu.net, or by
    allowing the Copyright Holder to include your modifications in

    the Standard Version of the Package.
  </li>

  <li>
    use the modified Package only within your corporation or

        organization.
    </li>

    <li>
      rename any non-standard executables so the names do not
    conflict with standard executables, which must also be
    provided, and provide a separate manual page for each
    non-standard executable that clearly documents how it differs

    from the Standard Version.
  </li>

  <li>
    make other distribution arrangements with the Copyright

        Holder.
    </li>

</ul>

<p>
  4. You may distribute the programs of this Package in object
  code or executable form, provided that you do at least ONE of the

  following:
</p>

<ul>

  <li>
    distribute a Standard Version of the executables and
    library files, together with instructions (in the manual page 
    or equivalent) on where to get the Standard Version.
  </li>

  <li>
    accompany the distribution with the machine-readable source 
        of the Package with your modifications.
    </li>

    <li>
      accompany any non-standard executables with their
    corresponding Standard Version executables, giving the
    non-standard executables non-standard names, and clearly
    documenting the differences in manual pages (or equivalent),
    together with instructions on where to get the Standard 
    Version.
  </li>

  <li>
    make other distribution arrangements with the Copyright 
        Holder.
    </li>

</ul>

<p>
  5. You may charge a reasonable copying fee for any
  distribution of this Package. You may charge any fee you choose
  for support of this Package. You may not charge a fee for this
  Package itself. However, you may distribute this Package in
  aggregate with other (possibly commercial) programs as part of a
  larger (possibly commercial) software distribution provided that

  you do not advertise this Package as a product of your own.
</p>

<p>
  6. The scripts and library files supplied as input to or
  produced as output from the programs of this Package do not
  automatically fall under the copyright of this Package, but
  belong to whomever generated them, and may be sold commercially,

  and may be aggregated with this Package.
</p>

<p>
  7. C or perl subroutines supplied by you and linked into this

    Package shall not be considered part of this Package.
</p>

<p>
  8. The name of the Copyright Holder may not be used to endorse
  or promote products derived from this software without specific

  prior written permission.
</p>

<p>
  9.Aggregation of this Package with a commercial distribution
  is always permitted provided that the use of this Package is
  embedded; that is, when no overt attempt is made to make this
  Package's interfaces visible to the end user of the commercial
  distribution. Such use shall not be construed as a distribution

  of this Package.
</p>

<p>
  10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS
  OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR 
  PURPOSE.
</p>
</page>

<page id="SOURCE" name="Source" requiresRole="none"
  title="JWAA Source Browser">

  <p>
    These links lead to documentation for configuration files and 
    Java classes as generated by <a idref="Doxygen">doxygen</a>.
  </p>

<dl>

<dt>Configuration Files (jwaa/root/jwaa)</dt> 

<dd>#foreach($f in ["application.xml", "innerPages.xml", "outerPages.xml", "velocity.macros"])
<a href="$self.link($f)">$f</a>
#end
</dd>

<dt>Core (edu.virtualschool.jwaa) </dt> 

<dd>#foreach($f in ["Config", "Fault", "GenericIdentifiable",
  "GenericLookAndFeel", "GenericPage", "GenericAccount", "GenericServlet",
  "GenericURI", "IgnorableFault", "Image", "IntervalTimer", "IOFault",
  "MetaPage", "AccountAbstraction", "RoleAbstraction", "Role", "RuntimeFault", "ServletFault", "StreamUtil", "StringUtil", "TimeUtil", "TreeNode", "UnixUtil", "UserFault", "Visitor"])
<a href="$self.link($f)">$f</a>
#end
</dd>

<dt>XML (edu.virtualschool.jwaa.xml)</dt> 

<dd>#foreach($f in [ "ApplicationElement", "FormElement", 
  "FileNotFoundFault", "IOFault",
  "PageElement", "PagesElement",
  "RootElement", "PageNotFoundFault", "ValidationFault", "VelocityEngine", "XMLFault", "Controller", "JwaaServlet", "XMLUtil"])
<a href="$self.link($f)">$f</a>
#end
</dd>

<dt>DBMS (edu.virtualschool.jwaa.dbms)</dt> 

<dd>#foreach($f in ["DB", "DBPool", "DBQuery", "DBUpdate", "DBUtil"])
<a href="$self.link($f)">$f</a>
#end
</dd>

<dt>Fields (edu.virtualschool.jwaa.field)</dt> 
<dd>#foreach ($f in ["FileField", "CityField", "ClassField", "CommaSeparatedField", "CountryField", "DoubleField", "EmailField", "FieldUtil", "GenericField", "IdentifierField", "IDField", "IntegerField", "LongField", "NameField", "OpField", "PassField", "PathField", "PhoneField", "StreetField", "TextField", "UrlField", "USStateField", "Validatable", "YesNoField", "ZipcodeField"]) 
<a href="$self.link($f)">$f</a>
#end
</dd>

</dl>
</page>

<page id="INSTALLATION" name="Installation" requiresRole="none"
  title="Installation and Configuration Instructions" >
  <child idref="CONFIGURATION"/>
  <child idref="TROUBLESHOOTING"/>

<h2>Prerequisite Software</h2>

  <p>
    We'll assume this prerequisite software is already installed
    and propertly configured. Each comes with its own instructions,
    which won't be repeated here.
  </p>

  <ol>

    <li>
      <a idref="Apache">Apache</a> (or equivalent) web server.
    </li>

    <li>
      <a idref="MySQL">MySQL</a>: Any recent version that supports 
      transactions (InnoDB) will do. Other relational databases may work 
      with minor changes but this has not been tested.  Be sure to 
      assign a root password as described in its instructions. Confirm 
      that it is working properly before proceeding.
    </li>

    <li>
      <a idref="Java">Java</a>: Download a recent version of the
      Java Software Development Kit (SDK). Avoid the Java Runtime 
      Environment version (JRE) which is significantly smaller but 
      only capable of running Java, not compiling it.
    </li>

    <li>
      <a idref="Jetty">Jetty</a> or <a idref="Tomcat">Tomcat</a>:
      Jetty is smaller and faster. Either will do.
    </li>

  </ol>

  <p>
    You will need these installed on the private computer you'll use 
    to test your work privately and also on the public server you'll
    copy your work to so others can see it.  I'll refer to the first
    machine as your <i>development</i> or <i>private</i> machine and 
    the other as your <i>deployment</i> or <i>public</i>machine.
  </p>

<h2>The JWAA Distribution Directory Structure</h2>

  <p>
    Unpack the distribution archive in your web server's document root 
    directory.  If this is /var/www/html, you'd type:
  </p>

  <pre>
  cd /var/www/html
  tar zxf path/to/jwaa.tgz 
  </pre>

  <p>
    This will create a new directory, /var/www/html/jwaa,
    that will be called the <i>installation</i> directory
    or simply <i>jwaa</i> for brevity. This directory contains:
  </p>

  <dl>

  <dt>root, root/jwaa</dt>

  <dd>
    The subdirectories of the jwaa/root directory define each JWAA 
    application.  JWAA is intially distributed with one such 
    subdirectory, jwaa/root/jwaa. This defines the pages you're
    reading now as three XML files.  
    <a idref="application.xml">application.xml</a> 
    defines the application as a whole, 
    <a idref="outerPages.xml">outerPages.xml</a>
    defines the external pages (the pages that are accessible
    without logging in) and 
    <a idref="innerPages.xml">innerPages.xml</a> 
    defines the inner pages (the demo application which requires
    logging in via the <a idref="PORTAL">Demo</a> link at the top 
    right of each page.).
  </dd>

  <dd>
    The root directory can be moved if you want by changing the line
    that defines its location in WEB-INF/web.xml.
  </dd>

  <dt>WEB-INF</dt>

  <dd>
    The servlet deployment directory contains a web.xml file
    for the JWAA servlet and a lib directory.  The lib directory 
    contains jwaa.jar with jwaa's java components plus the libraries
    that jwaa.jar depends on. These include the latest versions of
    commons-collections.jar, gnu-regexp-1.1.4.jar, jaxen-core.jar, 
    jaxen-jdom.jar, jdom.jar, junit.jar, jwaa.jar, log4j-1.2.8.jar, 
    mysql-connector-java-3.0.10-stable-bin.jar, saxpath.jar,
    velocity-1.5-dev.jar, xerces.jar, and xml-apis.jar. All are
    standard packages except for velocity. The a pre-release 
    version is included which repairs an incompatibility between
    Velocity and XML entity syntax by accepting "and" as a synonym
    for the problematic &amp;&amp;.
  </dd>

  <dt>sql</dt>

  <dd>
    This directory contains a MySQL script that you'll use to define
    the JWAA database.
  </dd>

  <dt>src</dt>

  <dd>
    This directory contains the source for the Java components of the
    JWAA distribution
  </dd>

  <dt>index.html</dt>

  <dd>
    The JWAA home page is distributed as a conventional static html
    file, index.html. Confirm that this page is accessible at the url
    <a href="http://localhost/jwaa">http://localhost/jwaa</a>. The
    links inside this page will not be accessible until Apache has
    been configured to route them to the servlet engine and the servlet
    engine has been configured to route them to the JWAA servlet.
  </dd>

  <dd>
    Once these configuration steps have been completed, the JWAA home
    page will also be accessible as a dynamic page at the URL
    <a href="http://localhost/jwaa/xml/jwaa/OUTER">http://localhost/jwaa/xml/jwaa/OUTER</a>.
    The index.html file is periodically generated by browsing the dynamic
    URL and saving the result as index.html. This ensures that the
    home page is accessible even when the servlet engine is down
    and makes this page accessible to search engines that might be 
    unable to access servlet-based pages.
  </dd>

  </dl>

<h2>MySQL Initialization</h2>

  <p>
    These instructions assume that MySQL has been installed by
    following its own instructions and is working propertly. 
    All that remains is defining a database for JWAA to use,
    defining a MySQL user with ownership rights for that
    database, assigning that user a secure password, and 
    conveying this information to JWAA by editing jwaa's
    application.xml file.
  </p>

  <p>
    The sql directory contains a sql script, initialize_jwaa_database.sql.
    This script initializes the jwaa database (dropping any existing one; 
    careful!) and creates a user, jwaa, with full permissions on that 
    database.  Edit the script before using it. AT THE VERY LEAST change 
    the password to something secret! Then run the script by typing:
  </p>

  <pre>
  mysql &lt;sql/initialize_jwaa_database.sql 
  </pre>

  <p>
    Then specify the same password in the jdbc section of 
    root/jwaa/application.xml. JWAA uses JDBC and should work 
    with any database but this has not been tested. 
  </p>

  <p>
    See <a href="CONFIGURATION">the configuration instructions</a>
    for how to configure these systems to work together properly.
  </p>

  </page>

  <page id="CONFIGURATION" name="Configuration" requiresRole="none"
    title="Configuring Apache, Servlet Engine, and JWAA" >

  <p>
    Jetty contains its own HTTP server so Apache isn't actually necessary.
    However many installations will prefer to let Apache's C code service 
    static web pages and route only the specific URLs that require dynamic 
    behavior to Jetty, which being written in Java, is arguably not as fast.
  </p>

  <p>
    Apache's world consists of an incoming stream of slash-delimited names 
    which Apache treats as pathnames to files within its document root 
    directory. If the requested file exists, Apache returns that file to 
    the browser, else it returns an error message. 
  </p>

  <p>
    This is an oversimplification because Apache is (almost) infinitely 
    configurable.  Our first task is to configure Apache to treat URLs 
    beginning with a specially desig