MyBank

JCO

JWAA

Java+

ALE

Academia

Mideast

Cox

Installation

Documentation

Source

Changes

License

Demo

obsoletePages.xml

<pages title="Obsolete Pages">
  <page id="Demo" name="Demonstration" requiresRole="none"
    title="Jwaa Demo Application" >

  <p><img align="right"
       src="/jwaa/pix/states.gif"
       width="167"
       height="177" />The six pages that make up the demo
       application are shown in this figure as ovals with the 
       hotlinks that connect them as arrows.</p>

  <p>Each of the pages in this figure are generated by objects,
  called <i>Page Objects</i>. These are defined by classes that you define
  while developing your application. Browsers issue page requests
  with urls of the form 
  <pre> http://hostname:port/contextName/servletName/pageName...</pre>.
  If a servlet engine (for example, #link("Jetty") is configured to
  listen to that port on that host, it routes the request to the
  servlet configured to respond to the specified <code>context</code>and 
  <code>servlet</code>and the servlet dispatches the request to the
  desired page based on the url. You define the servlet and several 
  other glue classes as will be described later.</p>

  <p>Every page is defined by a Page class, each of which defines a
  MetaPage, a no-args constructor, and a run method as shown here:</p>

  <p>The PageMapping provides a unique name for each page. It must
  be consistent with the &lt;servlet-mapping&gt; entry of your
  web.xml file. For example, if &lt;servlet-name&gt; is /foo,
  &lt;servlet-mapping&gt; is /bar/*, and the unique name of this
  page is gag, the PageMapping argument is /bar/gag. The servlet 
  name is automatically added as required.</p>

  <p>The servlet calls the no-args constructor to create a page
  instance, initializes the instance with information it needs to
  respond to browser requests, and calls the instance's run method
  to handle the request. The MetaPage instance bundles static
  information about the page's relationship to other pages and will 
  be described later.</p>

  <p>The run method is where all the action happens. For
  non-interactive pages (pages that don't process forms), the run
  method simply sends html text to the browser (via the 
  <code>page.send(...) call outlined above</code>). Interactive
  pages can be considerably more elaborate since they must decide 
  what to send based on form parameter inputs.</p>

  <h2>Templates</h2>

  <p>Multi-page web applications must do something to ensure that
  the site's standard look and feel is preserved as the user moves
  from page to page. In Jwaa, the solution is to define a 

  <code>Template</code>class with static methods that the run
  methods call to compute the standard html boilerplate at the
  beginning and end of each page. For example, run methods are 
  typically coded like this:</p>

  <pre>
 public final void
run() throws Fault {
 page.send(...);
} 
</pre>

  <p>JWAA's only requirement is that a run method exist to send the
    response to the browser. It does not constrain <i>how</i> run methods 
    compute that response. One common approach, <i>separation of concerns</i>, 
    reads the response text from files, often with the aid of a 
    template engine like #link("Velocity"). The other, 
    <i>integration of concerns</i>, maintains text as strings 
    within the application.  This will take the latter approach 
    because this is the approach used in the Demo applications.</p>

  <h2>Multi-line Strings</h2>send html boilerplate at the
  beginning/end of each page and the page.send(...) call sends the
  page content. It would be tedious to write long (multiline) text
  as Java Strings. #link("JavaPlus") simply provides a syntax that
  makes long strings much easier to manage than plain Java strings.

  <p>For example, #link("INNER") shows how everything we've
  discussed so far works in practice. Notice that the page's
  content is a single long string enclosed in Java+ string
  delimiters (

  <code>{{...}}</code>)</p>

  <h2>Executable Inclusions</h2>

  <p>Notice that the long string contains java code enclosed in
    embedded <code>{{...}}</code>delimiters (for example at the 
    beginning of the second paragraph). These are <i>executable inclusions</i>; 
  Java expressions embedded within strings to be evaluated and 
  spliced into the surrounding string at run-time.</p>

  <p>Executable inclusions are a generally useful feature. One
  common use is supporting compile-time checking of cross-page
  references, or hotlinks. The first paragraph shows the
  conventional technique in which pages reference other pages (or
  in this case, a graphic) by hard-coding &lt;a href=""&gt; (or in 
  this case, an &lt;img...&gt; command) into the html.</p>

  <p>The JWAA alternative is shown in the second paragraph. An
  executable inclusion is used to splice the output of the 
  <code>link</code>command into the surrounding string. The link
  command's argument, EntryPage.meta, identifies the target page
  such that if the page is ever renamed or moved, a compile-time
  error will report the error rather than letting the user discover 
  the problem at run-time as in the first approach.</p>

  <p>Another improvement is less obvious. Java servlets provide two
  techniques for tracking session information: cookies and
  url-rewriting. When a user logs in successfully, their identity
  is typically recorded as a cookie as they move from page to page.
  However some browsers don't support cookies, and some users turn
  them off, so the fallback technique, url rewriting, is needed for
  the system to remember who they are. But url rewriting only works
  when each and every url is generated on-the-fly, and is of no use
  when urls are hard-coded inside html text. By habitually adopting
  the JWAA technique, user sessions are automatically preserved
  even when the system can't count on cookies for maintaining the 
  user's identity.</p>

  <h2>Meta Pages</h2>

  <p>Notice that the link command's argument ends in .meta. This is
  the first, and simplest use of the MetaPage object that was
  defined without explanation in the ExamplePage example. By
  convention, every page class defines a public final static
  variable, named meta. Other pages rely on this variable for 
  generating hotlinks to that page as demonstrated above.</p>

  <p>Also notice that the link command in this example contains a
  second argument, "Click here". If this argument were omitted, the
  anchor text of the emitted url would have been as defined in the
  MetaPage constructor argument, "Entry" in this case. But since we
  wanted the anchor to read "Click here" in this case, we overrode 
  the default by providing the additional argument.</p>

  <p>This is only the simplest example of how the MetaPage is used.  
  #link("MetaPageDox" "Click here") for a complete discussion.</p>

  <h2>Rewriting here</h2>

  <p>Each page is a subclass of #link("GenericPage"), and they
  reference other pages by calling the <code>link, form, redirect 
  or forward</code>methods that they inherit with the target page 
  as an argument. Since Java checks all object references at compile 
  time, if the target page doesn't 
  exist, the error will be reported at compile time.</p>

  <p>JwaaPage defines several abstract methods such that each
  subclass must implement the following methods. In addition, pages
  can and often do define additional methods to support the 
  mandatory ones listed here</p>

  <dl>

    <dt>public PageName()</dt>

    <dd>Each page class must be public and must define a public
    no-args constructor. The application's servlet uses the
    constructor to create an instance of your Page class to handle
    the request. It then calls the instance's public final void
    init() populate the Page's four instance variables with the
    request-specific information that the page needs to handle the
    request: 

    <ol>

      <li>The servlet that dispatched the request</li>

      <li>The HttpServletRequest instance</li>

      <li>The HttpServletResponse instance</li>

    </ol></dd>

    <dt>public final static MetaPage meta = new MetaPage(...)</dt>

    <dd>Every page defines a global handle, by convention named
    "meta", that other pages will use to reference the page in
    hotlinks, form references, redirects and forward commands. This
    structure would be the page's meta class in other
    object-oriented languages. Think of it as the page's factory
    object because it provides a way to create instances of the
    page and maintains information that must be known even when no

    instances of the page are available.</dd>

    <dt>public void run() throws Fault</dt>

    <dd>The page's run method sends the page's html to the browser
    and processes form parameters that the browser returns as its

    response.</dd>

  </dl>

  <h3>MetaPage</h3>

  <p>#link("LOGOUT") is the simplest page in the demo, but it
  contains all of the elements that are required of all pages.
  Notice the MetaPage constructor, which takes the following 
  parameters:</p>

  <ul>

    <li>The first is the page's class. The servlet uses this to
    construct an instance of the page to service each page 
    request.</li>

    <li>The second is the page's dispatch key. This is a unique
    name for each page. The form and link commands will use this to 
    compose the URL that browsers use to refer to the page.</li>

    <li>The third is a brief string (ideally one word) that the
    link method will use as the anchor text in navigation bars and
    hotlinks if an explicit anchor is not provided as an 
    argument.</li>

    <li>The fourth is a longer string that the link method will use
    as the default title string in navigation bars, page titles and
    hotlinks, if an explicit title is not provided as an 
    argument.</li>

    <li>The fifth determines who can access the page. It must be an
    an object that abides by JWAA's #link("GenericRole") interface,
    such as #link("Role"). This class defines three capability
    levels, Visitor for those who have not registered and logged
    in, Registered for those who have, and Admin for specially
    authorized administrative accounts. The capability parameter
    determines whether the navigation bar will offer links to that
    page and whether the servlet will dispatch requests for that
    visitor. The servlet will redirect unauthorized requests to the 
    page specified by the servlet's getRefusePage() method.</li>

    <li>The sixth defines this page's contribution to the page
    hierarchy as an MetaPage[] array of sub-pages. This parameter
    is optional because the notion of "hierarchy" is not intrinsic,
    but is often added to help users understand and navigate the 
    site.</li>

  </ul>

  <p>The Meta structures must abide by the following rules, which
  are checked when the servlet engine is starting up. Violations
  are not fatal but are logged to the log file to warn you to fix

  them.</p>

  <ul>

    <li>Each page's dispatch key must be globally unique since

    external browsers use this to uniquely identify the page.</li>

    <li>Each page may not be a child of multiple parents. The page
    hierarchy is a tree, not a graph, and is managed as a doubly

    linked parent-child tree.</li>

    <li>Pages that are in the hierarchy will be automatically
    loaded when the servlet engine is starting up. The trigger is
    that #link("JwaaServlet") is imported (by the
    #link("GenericServlet") interface), which references the root
    of the page hierarchy #link("JwaaPage"). If a page does not
    appear in the hierarchy, the class loader won't load it. Pages
    that aren't in the hierarchy must be explicitly referenced
    elsewhere or they will not be registered in the dispatch table

    so dispatches will fail.</li>

  </ul>

  <h3>Run Method</h3>

  <p>A page's meta object specifies its static nature and its
  dynamic nature is determined by its run method.
  #link("LOGOUT") has the simplest run method, because it sends
  nothing at all to the browser. It simply logs the visitor out by
  calling setViewer(null) to erase the viewer's account information

  from the session and forwards control elsewhere.</p>

  <p>#link("INNER") is more typical. Its run method uses the
  send method (that all pages inherit from #link("JwaaPage")) to
  send a long batch of HTML text to the browser. The problem here
  is how to write the HTML, since Java's String syntax is oriented 
  to short uni-line strings. $fixme()</p>

  <p>A final refinement is to eliminate the leading and trailing
  html that define the site's look and feel by moving it into
  static methods of an application-specific JwaaPage.template
  class. With these two refinements, the run method of a simple

  "Hello World" application would be written like this:</p>

  <pre>
 send({{&lt;h1&gt;Hello world&lt;/h1&gt;}});


</pre>

  <p>See #link("INNER") and #link("JwaaPage") for fully

  elaborated examples.</p>

  <h3>Cross-page References</h3>

  <p>Although you can always write &lt;a href&gt; and &lt;form&gt;
  commands as hard-coded strings within the html, JWAA provides a
  new technique that does exactly the same thing but allows linkage 
  errors to be detected at compile-time.</p>

  <p>All pages inherit link, form, forward, and redirect methods
  from #link("JwaaPage") which all require a MetaPage instance as
  their first argument. The link and form commands return the
  appropriate &lt;a href&gt; or &lt;form&gt; command as a String
  while the forward and redirect commands actually redirect control
  to the specified page. Java's strong type-checking automatically
  determines if the MetaPage structure is not accessible. For 
  example, the Hello World example might be extended like this:</p>

  <pre> 
 send({{
&lt;h1&gt;Hello world&lt;/h1&gt; {{link(SomeOtherPage.meta, "Click
here")}} for more information.  }}); 
</pre>

  <p>See #link("INNER") for a longer example.</p>

  <h3>Interactive Pages</h3>

  <p>Non interactive pages (pages that don't process form
  parameters) typically handle everything in their run() method.
  Interactive pages, such as the #link("EDITOR") which supports
  editing of an account's registration information, confine the run
  method to specifying the page's logic and handle presentation
  elsewhere, either in a private method of the same class
  (integration of concerns) or in a separate file (separation of

  concerns) as described #link("INTERACTION" "here").</p>

  <p>The #link("PORTAL"), #link("EDITOR"),
  #link("RegisterPage"), and #link("ADMIN") pages provide fully
  developed examples of the integration of concerns approach.
  Notice that the control logic invariably follows this simple

  pattern:</p>

  <ol>

    <li>Gather the form parameters by using getField to build

    #link("Field") instances.</li>

    <li>If all field instances are valid, process them.</li>

    <li>Otherwise prompt the user to fix them.</li>

  </ol>

  <p>The else clause automatically handles the initial presentation
  of the page, when all fields contain default values (typically
  empty ones), and subsequent presentations in which one or more
  fields contain errors that the user must fix to proceed. Notice
  that the run method boils down to a few initialization statements 
  and an if statement. It can't get any simpler than that!</p>

  <h2><a name="mortar" id="mortar">Support Classes: the Mortar</a></h2>

  <p>In addition to the Page classes described above, every
  application needs a number of supporting classes to glue the
  separate pages into a functioning application. The remaining
  sections describe the supporting classes for the demo 
  application.</p>
  
  </page>

<page id="OLD_DOCUMENTATION" name="Documentation" requiresRole="none"
title="Pages are atoms, applications the molecules" >
<logic />

<child idref="METAPAGES"></child> 
<child idref="ROLES"></child> 
<child idref="SERVLETS"></child> 
<child idref="MODELS"></child> 
<child idref="FIELDS"></child>


<p><img align="right" src="/jwaa/pix/states.gif" width="167" height="177" />
The six pages that make up the demo application are shown in this figure 
as ovals with the hotlinks that connect them as arrows.</p>

<p>Each of the pages in this figure are generated by objects,
called <i>Page Objects</i>. These are defined by classes that you define
while developing your application. Browsers issue page requests
with urls of the form 

<code> http://hostname:port/contextName/servletName/pageName...</code>.

If a servlet engine is configured to listen to that port on that
host, it routes the request to the servlet configured to respond
to the specified <code>context</code>and <code>servlet</code>.
The servlet dispatches the request to the desired page based on 
the url. You define the servlet and other glue classes as will be 
described later.</p>

<p>Every page is defined by a Page class, each of which defines a
MetaPage, a no-args constructor, and a run method as shown here:</p>

<pre>
 public class ExamplePage extends GenericPage { public final static
MetaPage meta = new MetaPage(
 ExamplePage.class, "PageMapping", "AnchorText", "TitleText",
 ...capability, new MetaPage[] { subPages.meta, }
); public ExamplePage() {} public final void run() throws Fault {
 page.send(...);
} }


</pre>The PageMapping argument must be a unique name for this page.
It must be consistent with the &lt;servlet-mapping&gt; defined in
your web.xml file. For example If servlet-name is foo,
servlet-mapping is bar, and the name of this page is gag the
PageMapping value must be /bar/gag. The servlet-name is
automatically added as required. 

<p>The servlet calls the no-args constructor to create a page
instance, initializes the instance with information it needs to
respond to browser requests, and calls the instance's run method
to handle the request. The MetaPage instance bundles static
information about the page's relationship to other pages and will

be describe later.</p>

<p>The run method is where all the action happens. For
non-interactive pages (pages that don't process forms), the run
method simply sends html text to the browser (via the 

<code>page.send(...) call outlined above</code>). Interactive
pages can be considerably more elaborate since they must decide

what to send based on form parameter inputs.</p>

<h2>Templates</h2>

<p>Multi-page web applications must do something to ensure that
the site's standard look and feel is preserved as the user moves
from page to page. In Jwaa, the solution is to define a 

<code>Template</code>class with static methods that the run
methods call to compute the standard html boilerplate at the
beginning and end of each page. For example, run methods are

typically coded like this:</p>

<pre>
 public final void
run() throws Fault {
 page.send(...);
}


</pre>

<p>Note that JWAA's only requirement is that a run method sends a
response to the browser. It does not constrain 

<i>how</i>run methods compute that response. One approach,
emphasizing 

<i>separation of concerns</i>, is to read the response text from
a file, typically with the aid of a template engine such as
Velocity. The separation of concerns approach is described 
separately, see #link("INTERACTION" "Dynamic Content").</p>

<p>A different approach, emphasizing 
<i>integration of concerns</i>, is to maintain the response text
as strings within the application. I will emphasize the latter
approach here because this is the approach used in the Demo

applications.</p>

<h2>Multi-line Strings</h2>send html boilerplate at the
beginning/end of each page, and send(...) sends the page content.
It would be tedious to express long (multiline) text as Java
Strings, so #link("Java+") was developed to support syntax for
long strings that isn't as tedious as Java string syntax. 

<p>#link("INNER") demonstrates everything we've discussed
so far. Notice that the page's content is a single long string
enclosed in Java+ string delimiters (

<code>{{...}}</code>)</p>

<h2>Executable Inclusions</h2>

<p>Notice that the long string contains java code enclosed in
embedded 

<code>{{...}}</code>delimiters (for example at the beginning of
the second paragraph). These are 

<i>executable inclusions</i>; Java expressions embedded within
strings to be evaluated and spliced into the surrounding string

at run-time.</p>

<p>Executable inclusions are a generally useful feature. One
common use is supporting compile-time checking of cross-page
references, or hotlinks. The first paragraph shows the
conventional technique in which pages reference other pages (or
in this case, a graphic) by hard-coding &lt;a href=""&gt; (or in

this case, an &lt;img...&gt; command) into the html.</p>

<p>The JWAA alternative is shown in the second paragraph. An
executable inclusion is used to splice the output of the 

<code>link</code>command into the surrounding string. The link
command's argument, EntryPage.meta, identifies the target page
such that if the page is ever renamed or moved, a compile-time
error will report the error rather than letting the user discover

the problem at run-time as in the first approach.</p>

<p>Another improvement is less obvious. Java servlets provide two
techniques for tracking session information: cookies and
url-rewriting. When a user logs in successfully, their identity
is typically recorded as a cookie as they move from page to page.
However some browsers don't support cookies, and some users turn
them off, so the fallback technique, url rewriting, is needed for
the system to remember who they are. But url rewriting only works
when each and every url is generated on-the-fly, and is of no use
when urls are hard-coded inside html text. By habitually adopting
the JWAA technique, user sessions are automatically preserved
even when the system can't count on cookies for maintaining the

user's identity.</p>

<h2>Meta Pages</h2>

<p>Notice that the link command's argument ends in .meta. This is
the first, and simplest use of the MetaPage object that was
defined without explanation in the ExamplePage example. By
convention, every page class defines a public final static
variable, named meta. Other pages rely on this variable for

generating hotlinks to that page as demonstrated above.</p>

<p>Also notice that the link command in this example contains a
second argument, "Click here". If this argument were omitted, the
anchor text of the emitted url would have been as defined in the
MetaPage constructor argument, "Entry" in this case. But since we
wanted the anchor to read "Click here" in this case, we overrode

the default by providing the additional argument.</p>

<p>This is only the simplest example of how the MetaPage is used.

See #link("MetaPageDox") for more information.</p></page>

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

<logic />

<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 #link("Role").</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>In practice, the pages of a web application can be thought
of as an outer lobby with the pages that should be accessible
to everyone, and an inner sanctum with the pages that can only
be accessed by those who have logged in. In the demo
application, the inner sanctum consists of only three pages.
#link("EDITOR") supports editing an account's registration
information, #link("LOGOUT"), supports logging out, and
#link("AdminPage"), is available only to administrative

users.</p>

<p>#link("PORTAL") is the doorway between the two regions.
Until a visitor has registered and logged in, their account is
null, signifying a special account reserved 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), #link("PORTAL")loads the account's
persistent information from the database as an instance of
#link("AccountAbstraction") 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 #link("DemoAccount") implements the
#link("AccountAbstraction") 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>#link("LookAndFeelDox") 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>#link("GenericServlet") 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="SERVLETS" name="Servlets" requiresRole="none"
title="Servlets are the top-level control point for an application" >

<p>Each web application defines an instance of
#link("GenericServlet") to handle all requests by that
application. Every application's servlet simply overrides the
following methods. For example, see the demo's servlet class, 
#link("JwaaServlet").</p>

<dl>

<dt>public void init(ServletConfig servletConfig) throws

ServletException</dt>

<dd>All servlets override this method. Nothing special

here.</dd>

<dt>public final MetaPage getDefaultPage() { return

DemoHomePage.meta; }</dt>

<dd>The page to be displayed if the servlet can't locate the
page named in the browser request. This might happen if the
user composes the request manually. Another possibility is
that the page is not registered in the page dispatch table
because it was not loaded by the class loader, as might
happen if the page is not listed as a child of some other

page in the page hierarchy.</dd>

<dt>public final MetaPage getRefusePage() { return

EntryPage.meta; }</dt>

<dd>This is the page the servlet should dispatch to if the
user requests a page for which they don't have the required
capability. The demo handles this by silently forwarding them
to the default entrance page (EntryPage). Other applications

might forward to an explicit "permission denied" page.</dd>

<dt>private final static MetaPage rootPage = JwaaRoot.meta;

<br />public final MetaPage getRootPage() { return rootPage;

}</dt>

<dd>This method exists as a reminder that the servlet must
reference the root of the page hierarchy so that the class
loader will automatically load all pages in the hierarchy as
the servlet starts up. If you have pages that aren't listed
in the hierarchy, the servlet will be unable to dispatch them
since their name won't be defined in its dispatch table.
Eliminating the static variable above will not work; the root

reference must occur at load time, not run time.</dd>

</dl>

</page>

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

<logic></logic>

<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 #link("Validatable") interface,
which defines the protocol that all field implementations
adhere to. It also provides an abstract #link("Field") that

defines methods for subclasses to inherit.</p>

<p>The full list of Field classes is available in the
#link("SOURCE"). The ones used by the demo application are
#link("City"), #link("Country"), #link("Email"), #link("ID"),
#link("Identifier"), #link("Name"), #link("Op"), #link("Pass"),

#link("Phone"), #link("Street"), and #link("Zipcode").</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="METAPAGES" name="MetaPages" requiresRole="none"
title="MetaPages collect pages into hierarchies" >

<logic />

<p>The developer sees each page as just one of many
interconnected objects, the end-user wants to see them
organized into simple hierarchies, with a home page at the top
and clear navigational hints for moving from one to another.
JWAA supports both of these views. Each page is an object as
defined on the previous page. If pages are organized into
hierarchies via the MetaPage structure to be described here,
JWAA will generate navigational bars, such as those at the top

of this page, automatically.</p>

<p>Pages are instances of #link("GenericPage") subclasses that
are created by the servlet to handle each request and discarded
immediately thereafter. MetaPages, by contrast, are instances
of #link("MetaPage") that are created at load time by each page
class to initialize a 

<code>public final static</code>variable, named by convention, 

<code>meta</code>. The MetaPage maintains meta information
about Page instances, such as their url, the page's default
anchor and title strings, the accounts that permitted to access
that page (the 

<i>Capability</i>), and the page's position in the site's page

hierarchy.</p>

<p>JwaaPage defines several abstract methods such that each
subclass must implement the following methods. In addition,
pages can and often do define additional methods to support the

mandatory ones listed here</p>

<dl>

<dt>public PageName()</dt>

<dd>Each page class must be public and must define a public
no-args constructor. The application's servlet uses the
constructor to create an instance of your Page class to
handle the request. It then calls the instance's public final
void init() populate the Page's four instance variables with
the request-specific information that the page needs to
handle the request: 

<ol>

<li>The servlet that dispatched the request</li>

<li>The HttpServletRequest instance</li>

<li>The HttpServletResponse instance</li>

</ol></dd>

<dt>public final static MetaPage meta = new

MetaPage(...)</dt>

<dd>Every page defines a global handle, by convention named
"meta", that other pages will use to reference the page in
hotlinks, form references, redirects and forward commands.
This structure would be the page's meta class in other
object-oriented languages. Think of it as the page's factory
object because it provides a way to create instances of the
page and maintains information that must be known even when

no instances of the page are available.</dd>

<dt>public void run() throws Fault</dt>

<dd>The page's run method sends the page's html to the
browser and processes form parameters that the browser

returns as its response.</dd>

</dl>

<h3>MetaPage</h3>

<p>#link("LOGOUT") is the simplest page in the demo, but it
contains all of the elements that are required of all pages.
Notice the MetaPage constructor, which takes the following

parameters:</p>

<ul>

<li>The first is the page's class. The servlet uses this to
construct an instance of the page to service each page

request.</li>

<li>The second is the page's dispatch key. This is a unique
name for each page. The form and link commands will use this
to compose the URL that browsers use to refer to the

page.</li>

<li>The third is a brief string (ideally one word) that the
link method will use as the anchor text in navigation bars
and hotlinks if an explicit anchor is not provided as an

argument.</li>

<li>The fourth is a longer string that the link method will
use as the default title string in navigation bars, page
titles and hotlinks, if an explicit title is not provided as

an argument.</li>

<li>The fifth determines who can access the page. It must be
an an object that abides by JWAA's #link("GenericRole")
interface, such as #link("Role"). This class defines three
capability levels, Visitor for those who have not registered
and logged in, Registered for those who have, and Admin for
specially authorized administrative accounts. The capability
parameter determines whether the navigation bar will offer
links to that page and whether the servlet will dispatch
requests for that visitor. The servlet will redirect
unauthorized requests to the page specified by the servlet's

getRefusePage() method.</li>

<li>The sixth defines this page's contribution to the page
hierarchy as an MetaPage[] array of sub-pages. This parameter
is optional because the notion of "hierarchy" is not
intrinsic, but is often added to help users understand and

navigate the site.</li>

</ul>

<p>The Meta structures must abide by the following rules, which
are checked when the servlet engine is starting up. Violations
are not fatal but are logged to the log file to warn you to fix

them.</p>

<ul>

<li>Each page's dispatch key must be globally unique since
external browsers use this to uniquely identify the

page.</li>

<li>Each page may not be a child of multiple parents. The
page hierarchy is a tree, not a graph, and is managed as a

doubly linked parent-child tree.</li>

<li>Pages that are in the hierarchy will be automatically
loaded when the servlet engine is starting up. The trigger is
that #link("JwaaServlet") is imported (by the
#link("GenericServlet") interface), which references the root
of the page hierarchy #link("JwaaPage"). If a page does not
appear in the hierarchy, the class loader won't load it.
Pages that aren't in the hierarchy must be explicitly
referenced elsewhere or they will not be registered in the

dispatch table so dispatches will fail.</li>

</ul>

<h3>Run Method</h3>

<p>A page's meta object specifies its static nature and its
dynamic nature is determined by its run method.
#link("LOGOUT") has the simplest run method, because it
sends nothing at all to the browser. It simply logs the visitor
out by calling setViewer(null) to erase the viewer's account
information from the session and forwards control

elsewhere.</p>

<p>#link("INNER") is more typical. Its run method uses
the send method (that all pages inherit from #link("JwaaPage"))
to send a long batch of HTML text to the browser. The problem
here is how to write the HTML, since Java's String syntax is
oriented to short uni-line strings. JWAA relies on the

$fixme()</p>

<p>A final refinement is to eliminate the leading and trailing
html that define the site's look and feel by moving it into
static methods of an application-specific JwaaPage.template
class. With these two refinements, the run method of a simple

"Hello World" application would be written like this:</p>

<pre>
send({{&lt;h1&gt;Hello world&lt;/h1&gt;}}); 
</pre>

<p>See #link("INNER") and #link("JwaaPage") for

examples.</p>

<h3>Cross-page References</h3>

<p>Although you can always write &lt;a href&gt; and
&lt;form&gt; commands as hard-coded strings within the html,
JWAA provides a new technique that does exactly the same thing 
but allows linkage errors to be detected at compile-time.</p>

<p>All pages inherit link, form, forward, and redirect methods
from #link("JwaaPage") which all require a MetaPage instance as
their first argument. The link and form commands return the
appropriate &lt;a href&gt; or &lt;form&gt; command as a String
while the forward and redirect commands actually redirect
control to the specified page. Java's strong type-checking
automatically determines if the MetaPage structure is not
accessible. For example, the Hello World example might be 
extended like this:</p>

<pre>
 send({{
&lt;h1&gt;Hello world&lt;/h1&gt; {{link(SomeOtherPage.meta, "Click
here")}} for more information.  }}); 
</pre>

<p>See #link("INNER") for a longer example.</p>

<h3>Interactive Pages</h3>

<p>Non interactive pages (pages that don't process form
parameters) typically handle everything in their run() method.
Interactive pages, such as the #link("EDITOR") which
supports editing of an account's registration information,
confine the run method to specifying the page's logic and
handle presentation elsewhere, either in a private method of
the same class (integration of concerns) or in a separate file
(separation of concerns) as described #link("INTERACTION" 
"here").</p>

<p>The #link("PORTAL"), #link("EDITOR"), #link("RegisterPage"), 
and #link("AdminPage") pages demonstrate the integration of 
concerns approach. Notice that the control logic invariably 
follows this simple pattern:</p>

<ol>

<li>Gather the form parameters by using getField to build 
#link("Field") instances.</li>

<li>If all fields are valid, process them.</li>

<li>Else prompt the user to fix them.</li>

</ol>

<p>The else clause above automatically handles the initial
presentation of the page, when all fields contain default
values (typically empty ones). Subsequent presentations handle
the case where one or more fields contain errors that the user 
must fix to proceed. Notice that the run method boils down to 
a few initialization statements and an if statement. It can't 
get any simpler than that!</p>

<h2> <a name="mortar" id="mortar">Support Classes: the Mortar</a> </h2>

<p>In addition to the Page classes described above, every
application needs a number of supporting classes to glue the
separate pages into a functioning application. The remaining
sections describe the supporting classes for the demo
application: #link("JwaaPage"), #link("JwaaServlet") and

#link("Role").</p>

<h3>JwaaPage.template Class</h3>

<p>How a page emits its html is entirely up to the page's run
method. But the recommended style is to move common look and
feel issues into static methods of an application-specific
JwaaPage.template class so that look and feel can be shared by

all pages.</p>

<p>The demonstration application's JwaaPage.template class is
#link("JwaaPage"). It uses CSS (Cascading Style Sheets)
commands extensively. It also uses the MetaPage page hierarchy
to add navigational menus at the top of each page. To build
your own application, copy this class to an

application-specific new name and modify to suit.</p>

<h3>Servlet Class</h3>

<p>Each web application defines an instance of
#link("GenericServlet") to handle all requests by that
application. Every application's servlet simply overrides the
following methods. For example, see the demo's servlet class, 
#link("JwaaServlet").</p>

<dl>

<dt>public void init(ServletConfig servletConfig) throws

ServletException</dt>

<dd>All servlets override this method. Nothing special

here.</dd>

<dt>public final MetaPage getDefaultPage() { return

DemoHomePage.meta; }</dt>

<dd>The page to be displayed if the servlet can't locate the
page named in the browser request. This might happen if the
user composes the request manually. Another possibility is
that the page is not registered in the page dispatch table
because it was not loaded by the class loader, as might
happen if the page is not listed as a child of some other

page in the page hierarchy.</dd>

<dt>public final MetaPage getRefusePage() { return

EntryPage.meta; }</dt>

<dd>This is the page the servlet should dispatch to if the
user requests a page for which they don't have the required
capability. The demo handles this by silently forwarding them
to the default entrance page (EntryPage). Other applications

might forward to an explicit "permission denied" page.</dd>

<dt>private final static MetaPage rootPage = JwaaRoot.meta;

<br />public final MetaPage getRootPage() { return rootPage;

}</dt>

<dd>This method exists as a reminder that the servlet must
reference the root of the page hierarchy so that the class
loader will automatically load all pages in the hierarchy as
the servlet starts up. If you have pages that aren't listed
in the hierarchy, the servlet will be unable to dispatch them
since their name won't be defined in its dispatch table.
Eliminating the static variable above will not work; the root

reference must occur at load time, not run time.</dd>

</dl>

<h3>Capability Class</h3>

<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 capability system defined in

#link("Role").</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>In practice, the pages of a web application can be thought
of as an outer lobby with the pages that should be accessible
to everyone, and an inner sanctum with the pages that can only
be accessed by those who have logged in. In the demo
application, the inner sanctum consists of only three pages.
#link("EDITOR") supports editing an account's registration
information, #link("LOGOUT"), supports logging out, and
#link("AdminPage"), is available only to administrative

users.</p>

<p>#link("PORTAL") is the doorway between the two regions.
Until a visitor has registered and logged in, their account is
null, signifying a special account reserved 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), #link("PORTAL")loads the account's
persistent information from the database as an instance of
#link("DemoAccount") 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 #link("DemoAccount") implements the
#link("AccountAbstraction") 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>#link("JwaaPage") 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>#link("GenericServlet") 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>

<h3>Model Classes</h3>

<p>In addition to an application's user-interface components
(Views/Controllers) every application needs one or more Model
classes to manage the application's data as persistent

objects.</p>

<p>The demo's model class is #link("DemoAccount"), which
demonstrates the principle that <i>Fields are to models as atoms 
are to molecules.</i> Models are not defined in terms of basic 
Java types such as Strings. Rather the models' instance variables and
method arguments are uniformly declared in terms of objects
that abide by the #link("Validatable") interface. Since these
objects are typically implemented as subclasses of
#link("Field"), these higher-level classes are called Field

Classes.</p>

<h3>Field Classes</h3>

<p>Models are defined in terms of #link("Field")s, not Strings,

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 #link("Validatable") interface,
which defines the protocol that all field implementations
adhere to. It also provides an abstract #link("Field") 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. International contributions would be gratefully 
accepted.</p>

</page>

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

<logic />

<p>In addition to an application's user-interface components
(Views/Controllers) every application needs one or more Model
classes to manage the application's data as persistent 
objects.</p>

<p>The demo's model class is #link("DemoAccount").  <i>Fields 
are to models as atoms are to molecules.</i>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
#link("Validatable") interface. Since Validatable objects are
typically implemented as subclasses of #link("Field"), they are 
called Field Classes.</p>

</page>

<page id="PAGES" title="Defining Pages" requiresRole="none"> 
<logic />

<p>If the course is the skeleton and tasks are the meat, then
pages are the skin. They wrap the gory internals into an tidy
package that students use to learn about the course without 
being exposed to the gory details.</p>

<p>Those who are familiar with HTML markup should be aware that
XHTML is a markup language exactly like HTML except that strict
syntactic requirements are enforced. See the XHTML tutorial in

the reference section for details.</p>

<p>Right-click the Browsing link in the navigation bar to open
a browser window on these files so that you continue reading

about what they contain.</p>

<dl>

<dt>Step 1: Revise the home page</dt>

<dd>The page with the id="OUTER" attribute defines the
course's home page. Open a new browser window (continue
reading these instructions in your current window) and type
http://localhost/ale/root/YourCourseName in the location bar.
You'll see the contents of the home element displayed there.
Open YourCourseName/outerPages.xml in a text editor, make a
few changes in the content, save them, and click your
browser's reload button. Notice that the changes are

reflected in your browser.</dd>

<dd>You're might make errors when you do this so see the XML
link (top row in the navigation bar) for how to deal with

them.</dd>

<dt>Step 2: Page Hierarchies versus Page Sequences</dt>

<dd>JWAA provides two automated tools to support navigating
from page to page without having to hand-code navigational
links into each and every page. The navigation bar (the row
of hotlinks at the top of this page) is used to support
non-sequential navigation, which is usually what you want for
ordinary pages. The other, a menu of Prev, Save, Next
buttons, supports sequential navigation which is most
appropriate when you want to constrain navigation to 
sequential movement in structured tasks.</dd>

<dd>The two kinds of navigational aids are governed by the
child and logic elements at the beginning of each page. The
child elements specify which other pages (defined elsewhere
in this file) should be presented in the navigation bar as
children of the current page. For example Tasks, Pages,
LookAndFeel, and Java are children of the Reference Manual 
page.</dd>

<dd>Notice that each of these pages contain a &lt;logic/&gt;
element. This is a command to turn 

<b>off</b>the automatic logic that would otherwise add a row
of Prev/Save/Next buttons to each page. These are
inappropriate for hierarchical pages so the logic command
turns them off. Try deleting one temporarily and observe the

result.</dd>

<dt>Step 3: Complete your Outer Pages</dt>

<dd>Revise the home page and its child pages until they
reflect what you want for your course. Be careful not to
delete anything except what is specifically instructed. Many
of these pages, particularly those near the end, are required
to exist, and must have exactly the identifiers they have now
to be recognized by the system. Always be ready to undo any

changes that the system won't accept.</dd>

</dl>

<h2>References</h2>

<dl>

<dt>

<a href="http://www.w3schools.com/xhtml/">XHTML

Tutorial</a>

</dt>

<dd>An XHTML tutorial by W3Schools.</dd>

</dl>

</page>

<page id="BROADCAST" name="Broadcast" requiresRole="none"
title="Defining Simple Broadcast-style Pages"
>

<logic />

<p>Task pages that simply broadcast information in a
sequential, page by page manner, are built exactly as described 
in the Pages section. There are only two differences:</p>

<ol>

<li>Omit the &lt;logic/&gt; element from the page. This tells
JWAA to automatically present page flipper buttons
(Prev/Save/Next) at the top and bottom of the page. JWAA will

take it from there.</li>

<li>Omit the page's requiresRole="none" attribute. This tells
JWAA that to require that the student be logged in to access

this page.</li>

</ol>

<p>Being logged in is important. That is how JWAA knows how to
record that student's information in the database. Although
simple broadcast pages don't collect much information, not as
Interactive Pages do, the Talk to Me feature (the closing page
of each task) certainly does. It would be disconcerting to
reach the last page and be required to login to proceed.

Catching this early is important.</p>

</page>

<page id="INTERACTIVE" name="Interactive Pages" requiresRole="none"
title="Defining Interactive (Question/Answer) Pages"
>

<logic />

<p>Interactive task pages are exactly the same as ordinary
broadcast pages except that they contain special markup
commands to position question fields within the page

content.</p>

<p>Each field has an id="..." attribute whose sole
purpose is to uniquely identify the question within that page.
They are used as keys to identify student answers in the
database, so it is very important to not change them task after
the database has accumulated student work. Since they do take
up space in the database, I recommend using very short strings.
I generally use q0, q1, q2, etc. To insert new questions, use
q0a, q0b, etc. Anything convention will do so long as each
question on a page is given a unique id that
permanently identifies that question within that task and that
page. I'll number these examples according to this convention.
The text of the question is written as "mixed" content in the
body of the question element as shown in the following

examples.</p>

<dl>

<dt>essayField</dt>

<dd>These are used to present essay-style questions. The
question itself should be stated inside the body of the
essayField, like this 

<pre>
&lt;essayField id="q1"&gt; What is your opinion of that?
&lt;/essayField&gt;

</pre>which looks like this when the student encounters this page: 

<essayField id="q1">What is your opinion of

that?</essayField></dd>

<dt>textField, emailField, urlField, phoneField</dt>

<dd>These look exactly the same in the student's browser. The
only difference is that textFields are used for unstructured
information; the other three provide validation logic to
prevent the student from proceeding until the information is
syntactically valid. For example: 

<pre>
&lt;emailField id="q2"&gt; Type your email address here.
&lt;/emailField&gt;

</pre>Looks like this in the browser: 

<emailField id="q2">Type your email address

here.</emailField></dd>

<dt>choiceField</dt>

<dd>These (along with menuFields) are used for picking a
single correct answer from a list. They're used like this: 

<pre>
 &lt;choiceField
id="q3"&gt; A menu for choosing answers from a list of
alternatives &lt;choice id="1"&gt;Yes&lt;/choice&gt;
&lt;choice id="2"&gt;No&lt;/choice&gt; &lt;choice
id="3"&gt;Maybe&lt;/choice&gt; &lt;/choiceField&gt; 

</pre>Chose the correct answer from this list. 

<choiceField id="q3">

<choice id="1">Yes</choice>

<choice id="2">No</choice>

<choice id="3">Maybe</choice>

</choiceField></dd>

<dt>multiChoiceField</dt>

<dd>These are used for multiple choice questions, like this: 

<pre>
 &lt;multiChoiceField id="q3"&gt; Chose
as many answers as apply: &lt;choice
id="1"&gt;Yes&lt;/choice&gt;
&lt;choice id="2"&gt;No&lt;/choice&gt; &lt;choice
id="3"&gt;Maybe&lt;/choice&gt; &lt;/multiChoiceField&gt; 

</pre>Chose as many answers as apply: 

<multiChoiceField id="q3">

<choice id="1">Yes</choice>

<choice id="2">No</choice>

<choice id="3">Maybe</choice>

</multiChoiceField></dd>

<dt>menuField</dt>

<dd>These (or choiceFields) are for picking a single correct
answer from a list. They're used like this: 

<pre>
&lt;menuField id="q3"&gt; A menu for choosing answers from
a
list of alternatives &lt;choice
id="1"&gt;Yes&lt;/choice&gt;
&lt;choice id="2"&gt;No&lt;/choice&gt; &lt;choice
id="3"&gt;Maybe&lt;/choice&gt; &lt;/menuField&gt; 

</pre>Chose the correct answer from this list. 

<menuField id="q3">

<choice id="1">Yes</choice>

<choice id="2">No</choice>

<choice id="3">Maybe</choice>

</menuField></dd>

<dt>submitField</dt>

<dd>These are rarely used in ordinary task pages, but are
indispensable when the usual page by page sequencing of the
Prev/Save/Next buttons must be circumvented, in the login
page for example. Browsers use the &lt;input type="submit
...&gt; form that this element emits to submit form contents
to the server. JWAA automatically recognizes the
Prev/Save/Next submit button names as commands to save all
form contents on this page in the database and advance to the
next page. Pages that contain submitFields should provide a
&lt;logic;&gt; element that provides code to handle all this
explicitly. This will be described in the next section,

Structured Pages.</dd>

</dl>

<p>All of these features contain provisions for annotating
student answers with comments the instructor may provide on
each question during the review process. By default, instructor
comments are presented in a contrasting (red) font immediately
below the student's answer answer. A separate box is available

for commenting on the task as a whole.</p>

</page>

<page id="PROGRAMMABLE" name="ProgrammablePages" requiresRole="none"
title="Defining Programmable Pages" >

<logic />

<p>JWAA automatically allows pages to contain programmable
statements written in the Velocity Template Language (see the

References section for details).</p>

<p>The key to understanding the JWAA programming model is to
think of each page element is an active 

<b>program</b>, not just static data as with HTML pages. JWAA
provides programming logic automatically that is sufficient for
most pages. Programmable Pages differ only in that the
automatically provided logic is insufficient for some reason

and must therefore be provided manually.</p>

<p>The program that handles each page must deal with 

<b>two</b>entirely different events: sending the page's
contents to the browser and handling the information the
browser sends back when the student clicks a submit button.
Pages that need to override the logic that JWAA automatically
provides must somehow deal with the difference, which is where

the page's &lt;logic&gt; steps in.</p>

<p>Actually there's a step that proceeds both of these, the
step of parsing the XML file that actually defines each page
and getting it ready for execution. We'll start with that step,
then describe the remaining two halves of the process,
beginning with the process of displaying a page followed by the

process of responding to page submissions.</p>

<h2>Loading/Parsing the XML</h2>

<p>Recall that JWAA handles precisely two kinds of XML files:
course.xml, which defines the structure and schedule of the
course as a whole while pointing to additional xml files that

each define any number of pages.</p>

<p>XML is rather time-consuming to parse so pages are parsed
only as they are needed. So JWAA examines the modification time
on all XML files each time the contents of that file is
accessed, and converts it to an in-memory representation at
that time. Error conditions, such as XML errors, are noticed at
this time and reported as the page is being loaded. From then
on the XML format is irrelevant: the XML has been converted to

a network of Java objects in the server's memory.</p>

<p>The XHTML content of each &lt;page&gt; element is converted
at load time to a simple string much like an ordinary XHTML

file, with these differences:</p>

<ol>

<li>The velocity macros, \#header() and \#footer(), are
automatically inserted at the beginning and end of each
string of XHTML code. These macros will be interpreted when
the page is displayed to add XHTML boilerplate, navigation
bars, and the like to each page. These macros are described 
in more detail on the LookAndFeel page.</li>

<li>The content of each page is automatically rewritten to
replace JWAA's special markup language for each question
fields with the corresponding Velocity macro. For example,
&lt;textField&gt; is replaced with a string that calls the

velocity macro, \#textField(...).</li>

<li>If the page provides a &lt;logic&gt; element, it is
attached verbatim to the front of the text that the
Controller will pass to velocity to interpret. If not a call
to the velocity macro, #defaultLogic(), is placed there
instead. Notice that the processing logic is at the very
beginning of the information that velocity will interpret,
ahead of the automatically inserted \#header() and \#footer()

macro calls.</li>

</ol>

<p>If the XML parsing and validation is successful, the result
is an instance of the Java class, Page, that has two internal
variables set to ordinary Java strings, one containing logic
for processing the page when it is submitted and the other for

displaying the page itself.</p>

<h2>Page Processing Overview</h2>

<p>The controller's response to a page request involves the

following steps:</p>

<ol>

<li>The servlet engine creates a Controller instance,
initialized with a database connection (automatically
retrieved from a connection pool and automatically returned
there at the end), the httpServletRequest and
httpServletResponse objects (which the controller needs to
service the request), and the servlet that initiated the
request. Then it calls the Controller's run method. The
Controller is an instance of JWAA's GenericController class,

which is described in more detail in the reference list.</li>

<li>The Controller's run method decodes the the pathInfo
string to determine which page to display. Each Course object
manages an independent page lookup table which is why all

page identifiers for a given course must be unique.</li>

<li>The Controller retrieves the Person object of the
currently logged in user from the servlet's session object
and uses that to determine the user's Role (unknown because
they're not logged in, guest, student, faculty,
administrator, etc). The Role object is then used to
determine if the requested page should be provided and

redirects the request to a RequestDenied page if not.</li>

<li>The Controller then builds the Context object that all
Velocity code uses to communicate with the rest of the
system. The context object contains a reference to the
controller instance (named $self) a reference to the current
user (named $person), and the values of any form

parameters.</li>

<li>Finally, the controller retrieves the text of the page
from the Page object and passes that plus the context object

to the velocity engine for processing.</li>

<li>The velocity statements in the page's logic and body
sections can make arbitrary changes to the text. For example,
if statements may omit sections of the text, foreach
statements can loop over arbitrarily complex data structures,
macro calls can insert new text, and
$self.gotoPage(someOtherPage) can break the control flow by

sending control to some other page in midstream.</li>

<li>The controller sends whatever string the velocity engine
returns to the browser (and it may not return if the velocity
code calls gotoPage()), thus determining what is actually

displayed by the browser.</li>

</ol>

<p>In summary, the XML code for each page is converted at XML
load time into a single long string that is filtered at run
time by the velocity engine. The velocity engine interprets
velocity statements embedded in this text, returning a new
string that the Controller sends to the browser. We'll examine

how the embedded velocity statements work next.</p>

<h2>Velocity Statements</h2>

<p>Velocity reserves two characters from the usual HTML
character set, \# and \$, and uses them to trigger special
processing. The \# character is used to designate a macro call
or various other built-in velocity commands (\#if, \#foreach,
\#set), and the \$ character is reserved to indicate a
reference to something in the velocity context object. These
are described in detail in the velocity reference material,
along with how to escape these characters if you need them in

your XHTML document.</p>

<p>Open YourCourseName/innerPages.xml in a text editor and find
the page that defines the course locker (id="locker").
Notice the line a few lines down from the top that reads
&lt;h2&gt;Welcome \$person&lt;h2&gt;. Velocity just replaces
the string, \$person, with the string value of the context 
variable, person.</p>

<p>A few lines below that is a more complex example. This line
generates the person's mailing address by accessing address
information from inside that person's Person object; i.e.
\$person.name, \$person.street, \$person.city, \$person.state, 
\$person.zipcode, etc.</p>

<p>Such expressions can be arbitrarily complex. A few lines
below that is the expression,
\$self.emitLink(\$self.findPage("edit"), "Edit") that calls the
emitLink method of the "self" object (self is always the name
of the Controller for the current page), the first argument
being the result of calling the findPage() method of the
controller with the id of the desired page. See the
velocity reference manual for more information on how Velocity 
code interacts with Java code.</p>

<p>Finally, notice the \#foreach statements a bit further down.
These build the locker by looping through each lesson in the
course (\$self.course.lessons) and then looping through each 
task in the lesson (\$lesson.tasks).</p>

<h2>References</h2>

<ul>

<li>

<a href="http://jakarta.apache.org/velocity/user-guide.html">

Velocity User's Guide</a>is the most relevant.</li>

<li>

<a href="/jwaa">JWAA:</a>JWAA is baed on the Java Web
Application Architecture, which provides form validation,
page dispatching, and other support facilities that JWAA's

Java code relies on.</li>

<li>

<a href="http://jakarta.apache.org/velocity">

Other</a>Velocity references may be useful, particularly for

configuring.</li>

</ul>

</page>

<page id="DATABASE" name="Database" requiresRole="none"
title="Accessing the Database" >

<logic />

<p>Under construction</p>

</page>

<page id="CONFIGURING" name="Configuring" requiresRole="none"
title="Configuring JWAA" >

<logic />

<p>The simplest way to run JWAA involves only MySQL and a Jetty
(or Tomcat) servlet engine. A better but more complex way is to
install the servlet engine so that static data (graphics and
static web pages) are served by a web server such as Apache,
which being written in C, is faster that the servlet engine's
Java code. We will assume the latter because the former is

adequately covered by each servlet engine's instructions.</p>

<p>This means that each web page request is handled
(dispatched) by four different pieces of code: the web server
(we'll call that Apache; others are similar), the servlet
engine (we'll call that Jetty; others are similar), the JWAA
servlet, and the JWAA page controller/dispatcher. Each of these
must be configured to know which requests to dispatch
elsewhere, and configuring them all properly is by far the most
troublesome part of the installation process. This overview may

help understand what's involved:</p>

<ol>

<li>The web server (apache) breaks the URL down into parts
and routes the request according to what it finds there.
Somewhat oversimplified, the URL
virtualschool.edu:80/ale/root/course/page?foo=bar, is broken
down into virtualschool.edu:80 (the hostname and port
number), the context name (/ale), the context mapping
(/root), the pathInfo (/ale/root/ale), and the request
arguments (?foo=bar). The context name and mapping strings
determine which requests will be handled by directly to
apache or routed to one of the several servlet engines that
might be available on that server. This is described 
under #link("CONFIGURING).</li>

<li>If the context name and mapping correspond to a servlet
engine apache knows about, sends the pathInfo string and
arguments there, else it will process the request 
internally.</li>

<li>The servlet engine strips the context name and mapping
(/ale/root) from the request, and attempts to find a course
whose id matches the first part of whats left
(course). If it succeeds, it uses the remainder to search for
one of that course's pages and proceeds as described below.
Otherwise it issues a "can't find" response and gives 
up.</li>

<li>We now know the course and a specific page within that
course. The servlet engine builds an object for controlling
processing of that page (the "Controller"). It temporarily
allocates a database connection from a pool and initializes
that objects variables with the database connection, the
servlet, the httpRequest and httpResponse that it received
from the servlet engine. These are mainly useful to the
Controller, but it is occasionally useful for page logic to
know that this information is available there. The controller
also initializes one of its variables with the page being

served.</li>

<li>The controller then constructs the context object with
two variables via which velocity code will communicate with
the rest of the system. The context variable, $self, contains
a reference to the controller object. $person contains a
reference to the object that represents the person that is

currently logged in (if any).</li>

</ol>

</page>

<page id="CONCEPTS" name="Concepts" requiresRole="none"
  title="Conceptual Overview" >

<logic />

<p>JWAA supports two ways to package the logic (control) and 
presentation (HTML) parts of a web page.</p>

<dl>

<dt>Integration of concerns for stiffness</dt>

<dd>A stiff application is harder to break (or to get wrong in
the first place) because all interfaces are strongly
type-checked by the compiler. Integration of concerns handles
presentation in separate (typically private) methods of the
same file that specifies the logic. This style is best when a
single person is responsible for the page because everything is
specified in the same file. This reduces the surface area to
the barest minimum, and since Java can rigorously type check
all interfaces, there is less chance for things to break as the
application evolves. The disadvantage is that the application
must be recompiled and reloaded to see changes in the

browser.</dd>

<dt>Separation of concerns for flexibility</dt>

<dd>A flexible application is easier to change on the fly
because some changes don't require recompiling and restarting
the server. This philosophy is best in large shops in which
programmers are responsible for the application's logic and
user interface designers are responsible for the html. Although
this doubles the number of files, it lets HTML designers change

the HTML without recompiling and restarting the server.</dd>

</dl>

<p>The demo applications emphasize the integration of concerns
philosophy because the reduced surface area and type checking
advantages were compelling in my shop. This page provides
everything you need to use JWAA according to the integration of
concerns approach. The separation of concerns approach is
described under #link("INTERACTION" "Integrating JWAA with 
Velocity"), but relies on concepts described on this page.</p>

<ul>

<li>

<a href="#concepts">Key Concepts</a>

</li>

<li>

<a href="#bricks">Page classes as the bricks</a>

</li>

<li>

<a href="#mortar">Support classes as the mortar</a>.</li>

</ul>

<p>Each section provides #link("SOURCE") hotlinks to
the source code of the #link("DemoHomePage" "online demo") to

illustrate each point.</p>

<a name="concepts"

 id="concepts"></a>

<h2>Key Concepts</h2>

<p>At the highest level, a web application is a number of 
<a href="#bricks">page objects</a>, one for each page in your
application. A user's browser session begins at a "home" page
(specified by a configuration parameter) and advances to other
pages when the user clicks hotlinks or submit buttons. These page
objects are the bricks that make up the application. They are
joined by support classes to form the application as a whole.</p>

<h3>Pages are Objects not Files</h3>

<p>Most web application environments view web pages as files that
reference each other via &lt;a href&gt; and &lt;form&gt; commands
hard coded into each file. However web applications are not
browsers and need not abide by this convention. HTML is to a web 
application as ASCII is to Hello World.</p>

<p>So JWAA applications are composed of dynamic objects, called
pages, rather than static HTML files. When a page (the ovals in
the figure) references another page (the arrows in the figure),
it specifies the object by name rather than by naming the file
that contains its HTML. This simple change makes all the
difference. Invalid object names are automatically detected and
reported when the application is compiled, rather than going 
undetected until the link is clicked by some user.</p>

<h3>Model-View-Controller Paradigm + Fields</h3>

<p>

<img align="right" src="/jwaa/pix/mvc.gif" alt="" width="117" height="114" />
Trygvee Reenskaug introduced the
 Model-View-Controller (MVC) paradigm within Smalltalk during
 a summer visit to Xerox Parc. It spread from there to other

 languages.</p>

<dl>

<dt>Models</dt>

<dd>Models are objects that manage the application's persistent
state, usually by cooperating with a database of some sort. For
example, #link("AccountAbstraction") maintains account-holder
information (name, address, phone number, etc) for the demo
application by loading the account-holder's information from
the database when the user logs in, saving it thereafter as

necessary.</dd>

<dt>Views</dt>

<dd>Views present the model to the user by sending HTML to a
browser in our case. In the integration of concerns approach,
views are private methods of the class that implements each
page and are called as needed by the controller method. See
#link("INTERACTION" "Integrating JWAA with Velocity") for the 
separation of concerns approach.</dd>

<dt>Controllers</dt>

<dd>Controllers provide the logic for controlling the
interaction as a whole. In JWAA, each web page corresponds to a
subclass of Page. The dispatcher allocates instances of this
class to service each request. This instance's run method is

the page's controller.</dd>

<dt>Fields</dt>

<dd>In the original MVC paradigm, models were built from
primitive data types such as Strings. JWAA introduces
higher-level container objects, called Fields, for the same
effect. Fields also encapsulate the logic for validating user
inputs (does the field contain acceptable values?) and for
communicating errors to the user via the user interface. Fields
are a uniquely powerful unit of reuse that simplifies user

interface design and implementation.</dd>

</dl>

<a name="bricks"

 id="bricks"></a>

<h2>Pages are the Bricks</h2>

<p>

<img align="right"
 src="/jwaa/pix/states.gif"
 width="167"
 height="177" />The six pages that make up the demo
 application are shown in this figure as ovals with the
 hotlinks that connect them as arrows. Each page is a
 subclass of the abstract page controller class,
 #link("GenericPage"), and they reference other pages by
 calling the 

<code>link, form, redirect or forward</code>methods that they
inherit from JwaaPage with the target page as an argument. Since
Java checks all object references at compile time, if the target
page doesn't exist, the error will be reported at compile

time.</p>

<p>JwaaPage defines several abstract methods such that each
subclass must implement the following methods. In addition, pages
can and often do define additional methods to support the

mandatory ones listed here</p>

<dl>

<dt>public PageName()</dt>

<dd>Each page class must be public and must define a public
no-args constructor. The application's servlet uses the
constructor to create an instance of your Page class to handle
the request. It then calls the instance's public final void
init() populate the Page's four instance variables with the
request-specific information that the page needs to handle the
request: 

<ol>

<li>The servlet that dispatched the request</li>

<li>The HttpServletRequest instance</li>

<li>The HttpServletResponse instance</li>

</ol></dd>

<dt>public final static MetaPage meta = new MetaPage(...)</dt>

<dd>Every page defines a global handle, by convention named
"meta", that other pages will use to reference the page in
hotlinks, form references, redirects and forward commands. This
structure would be the page's meta class in other
object-oriented languages. Think of it as the page's factory
object because it provides a way to create instances of the
page and maintains information that must be known even when no

instances of the page are available.</dd>

<dt>public void run() throws Fault</dt>

<dd>The page's run method sends the page's html to the browser
and processes form parameters that the browser returns as its

response.</dd>

</dl>

<h3>MetaPage</h3>

<p>#link("LOGOUT") is the simplest page in the demo, but it
contains all of the elements that are required of all pages.
Notice the MetaPage constructor, which takes the following

parameters:</p>

<ul>

<li>The first is the page's class. The servlet uses this to
construct an instance of the page to service each page

request.</li>

<li>The second is the page's dispatch key. This is a unique
name for each page. The form and link commands will use this to

compose the URL that browsers use to refer to the page.</li>

<li>The third is a brief string (ideally one word) that the
link method will use as the anchor text in navigation bars and
hotlinks if an explicit anchor is not provided as an

argument.</li>

<li>The fourth is a longer string that the link method will use
as the default title string in navigation bars, page titles and
hotlinks, if an explicit title is not provided as an

argument.</li>

<li>The fifth determines who can access the page. It must be an
an object that abides by JWAA's #link("GenericRole") interface,
such as #link("Role"). This class defines three capability
levels, Visitor for those who have not registered and logged
in, Registered for those who have, and Admin for specially
authorized administrative accounts. The capability parameter
determines whether the navigation bar will offer links to that
page and whether the servlet will dispatch requests for that
visitor. The servlet will redirect unauthorized requests to the

page specified by the servlet's getRefusePage() method.</li>

<li>The sixth defines this page's contribution to the page
hierarchy as an MetaPage[] array of sub-pages. This parameter
is optional because the notion of "hierarchy" is not intrinsic,
but is often added to help users understand and navigate the

site.</li>

</ul>

<p>The Meta structures must abide by the following rules, which
are checked when the servlet engine is starting up. Violations
are not fatal but are logged to the log file to warn you to fix

them.</p>

<ul>

<li>Each page's dispatch key must be globally unique since

external browsers use this to uniquely identify the page.</li>

<li>Each page may not be a child of multiple parents. The page
hierarchy is a tree, not a graph, and is managed as a doubly

linked parent-child tree.</li>

<li>Pages that are in the hierarchy will be automatically
loaded when the servlet engine is starting up. The trigger is
that #link("JwaaServlet") is imported (by the
#link("GenericServlet") interface), which references the root
of the page hierarchy #link("JwaaPage"). If a page does not
appear in the hierarchy, the class loader won't load it. Pages
that aren't in the hierarchy must be explicitly referenced
elsewhere or they will not be registered in the dispatch table

so dispatches will fail.</li>

</ul>

<h3>Run Method</h3>

<p>A page's meta object specifies its static nature and its
dynamic nature is determined by its run method.
#link("LOGOUT") has the simplest run method, because it sends
nothing at all to the browser. It simply logs the visitor out by
calling setViewer(null) to erase the viewer's account information

from the session and forwards control elsewhere.</p>

<p>#link("INNER") is more typical. Its run method uses the
send method (that all pages inherit from #link("JwaaPage")) to
send a long batch of HTML text to the browser. The problem here
is how to write the HTML, since Java's String syntax is oriented

to short uni-line $fixme()</p>

<p>A final refinement is to eliminate the leading and trailing
html that define the site's look and feel by moving it into
static methods of an application-specific JwaaPage.template
class. With these two refinements, the run method of a simple

"Hello World" application would be written like this:</p>

<pre>
 send({{&lt;h1&gt;Hello world&lt;/h1&gt;}});


</pre>

<p>See #link("INNER") and #link("LookAndFeelDox") for fully

elaborated examples.</p>

<h3>Cross-page References</h3>

<p>Although you can always write &lt;a href&gt; and &lt;form&gt;
commands as hard-coded strings within the html, JWAA provides a
new technique that does exactly the same thing but allows linkage

errors to be detected at compile-time.</p>

<p>All pages inherit link, form, forward, and redirect methods
from #link("JwaaPage") which all require a MetaPage instance as
their first argument. The link and form commands return the
appropriate &lt;a href&gt; or &lt;form&gt; command as a String
while the forward and redirect commands actually redirect control
to the specified page. Java's strong type-checking automatically
determines if the MetaPage structure is not accessible. For
example, the Hello World example might be extended like

this:</p>send({{ &lt;h1&gt;Hello world&lt;/h1&gt;
{{link(SomeOtherPage.meta, "Click here")}} for more information.
}}); 

<p>See #link("INNER") for a longer example.</p>

<h3>Interactive Pages</h3>

<p>Non interactive pages (pages that don't process form
parameters) typically handle everything in their run() method.
Interactive pages, such as the #link("EDITOR") which supports
editing of an account's registration information, confine the run
method to specifying the page's logic and handle presentation
elsewhere, either in a private method of the same class
(integration of concerns) or in a separate file (separation of 
concerns) as described #link("INTERACTION" "here").</p>

<p>The #link("PORTAL"), #link("EDITOR"),
#link("RegisterPage"), and #link("AdminPage") pages demonstrate
the integration of concerns approach. Notice that the control

logic invariably follows this simple pattern:</p>

<ol>

<li>Gather the form parameters by using getField to build

#link("Field") instances.</li>

<li>If all field instances are valid, process them.</li>

<li>Otherwise prompt the user to fix them.</li>

</ol>

<p>The else clause automatically handles the initial presentation
of the page, when all fields contain default values (typically
empty ones), and subsequent presentations in which one or more
fields contain errors that the user must fix to proceed. Notice
that the run method boils down to a few initialization statements

and an if statement. It can't get any simpler than that!</p>

<h2>

<a name="mortar"

 id="mortar">Support Classes are the Mortar</a>

</h2>

<p>In addition to the Page classes described above, every
application needs a number of supporting classes to glue the
separate pages into a functioning application. The remaining
sections describe the supporting classes for the demo
application: #link("LookAndFeelDox"), #link("JwaaServlet") and

#link("Role").</p>

<h3>JwaaPage.template Class</h3>

<p>How a page emits its html is entirely up to the page's run
method. But the recommended style is to move common look and feel
issues into static methods of an application-specific
JwaaPage.template class so that look and feel can be shared by

all pages.</p>

<p>The demonstration application's JwaaPage.template class is
#link("LookAndFeelDox"). It uses CSS (Cascading Style Sheets)
commands extensively. It also uses the MetaPage page hierarchy to
add navigational menus at the top of each page. To build your own
application, copy this class to an application-specific new name

and modify to suit.</p>

<h3>Servlet Class</h3>

<p>Each web application defines an instance of
#link("GenericServlet") to handle all requests by that
application. Every application's servlet simply overrides the
following methods. For example, see the demo's servlet class,

#link("JwaaServlet").</p>

<dl>

<dt>public void init(ServletConfig servletConfig) throws

ServletException</dt>

<dd>All servlets override this method. Nothing special

here.</dd>

<dt>public final MetaPage getDefaultPage() { return

WelcomePagePage.meta; }</dt>

<dd>The page to be displayed if the servlet can't locate the
page named in the browser request. This might happen if the
user composes the request manually. Another possibility is that
the page is not registered in the page dispatch table because
it was not loaded by the class loader, as might happen if the
page is not listed as a child of some other page in the page

hierarchy.</dd>

<dt>public final MetaPage getRefusePage() { return

EntryPage.meta; }</dt>

<dd>This is the page the servlet should dispatch to if the user
requests a page for which they don't have the required
capability. The demo handles this by silently forwarding them
to the default entrance page (EntryPage). Other applications

might forward to an explicit "permission denied" page.</dd>

<dt>private final static MetaPage rootPage = JwaaRoot.meta;

<br />public final MetaPage getRootPage() { return rootPage;

}</dt>

<dd>This method exists as a reminder that the servlet must
reference the root of the page hierarchy so that the class
loader will automatically load all pages in the hierarchy as
the servlet starts up. If you have pages that aren't listed in
the hierarchy, the servlet will be unable to dispatch them
since their name won't be defined in its dispatch table.
Eliminating the static variable above will not work; the root

reference must occur at load time, not run time.</dd>

<dt>public final DBPool getConnectionPool() { return pool;

}</dt>

<dd>This method returns the connection pool that the servlet
should use to obtain database connections. The servlet
automatically checks out a new connection from the pool for
each dispatch, stores it as an instance variable in the page
instance that will handle that dispatch, calls the instance's
run() method, and automatically returns the connection to the

pool when the run method returns.</dd>

</dl>

<h3>Capability Class</h3>

<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 capability system defined in

#link("Role").</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>In practice, the pages of a web application can be thought of
as an outer lobby with the pages that should be accessible to
everyone, and an inner sanctum with the pages that can only be
accessed by those who have logged in. In the demo application,
the inner sanctum consists of only three pages.
#link("EDITOR") supports editing an account's registration
information, #link("LOGOUT") supports logging out, and 
#link("AdminPage"), is for administrative users.</p>

<p>#link("PORTAL") is the doorway between the two regions.
Until a visitor has registered and logged in, their account is
null, signifying a special account reserved 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), #link("PORTAL")loads the account's persistent
information from the database as an instance of
#link("AccountAbstraction") 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 #link("DemoAccount") implements the
#link("AccountAbstraction") 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>#link("LookAndFeelDox") 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>#link("GenericServlet") 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>

<h3>Model Classes</h3>

<p>In addition to an application's user-interface components
(Views/Controllers) every application needs one or more Model
classes to manage the application's data as persistent

objects.</p>

<p>The demo's model class is #link("DemoAccount"), which
demonstrates the principle that 

<i>Fields are to models as atoms are to molecules.</i>This means
that models are not defined in terms of basic Java types such as
Strings. Rather the models' instance variables and method
arguments are uniformly declared in terms of objects that abide
by the #link("Validatable") interface. Since these objects are
typically implemented as subclasses of #link("Field"), these

higher-level classes are called Field Classes.</p>

<h3>Field Classes</h3>

<p>Models are defined in terms of #link("Field")s, not Strings,

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 #link("Validatable") interface,
which defines the protocol that all field implementations adhere
to. It also provides an abstract #link("Field") that defines

methods for subclasses to inherit.</p>

<p>The full list of Field classes is available in

#link("SOURCE").</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.
International contributions would be gratefully accepted.</p>

</page>


</pages>