You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@velocity.apache.org by cb...@apache.org on 2012/03/09 17:23:32 UTC
svn commit: r1298906 [2/14] - in /velocity/sandbox/velosurf: ./ docs/
examples/ examples/ant-vpp/ examples/ant-vpp/lib/ examples/auth-l10n/
examples/auth-l10n/WEB-INF/ examples/auth-l10n/WEB-INF/lib/
examples/auth-l10n/WEB-INF/src/ examples/auth-l10n/e...
Added: velocity/sandbox/velosurf/docs/architecture.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/architecture.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/architecture.html (added)
+++ velocity/sandbox/velosurf/docs/architecture.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,112 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>Velosurf - Architecture</title>
+
+
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+
+</head>
+
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><b>Architecture</b></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<div id="body">
+ <h1>Architecture</h1>
+ <p>This section gives some elements on the inner architecture of Velosurf.</p>
+ <p>Here are the main packages of Velosurf:</p>
+ <ul>
+ <li><a href="./api/velosurf/package-summary.html"><code>velosurf</code></a> contains the Velosurf class, to be used when Velosurf is used embedded in a Java application other than a Webapp.</li>
+ <li><a href="./api/velosurf/cache/package-summary.html"><code>velosurf.cache</code></a> contains the cache (used by the <code>Entity</code> class).</li>
+ <li><a href="./api/velosurf/context/package-summary.html"><code>velosurf.context</code></a> contains all the classes that are to be populated
+ in Velocity contexts. Some of them are wrappers for internal classes (see the diagram below).</li>
+ <li><a href="./api/velosurf/model/package-summary.html"><code>velosurf.model</code></a> contains the classes that help modelize the data model
+ as reverse engineered and/or specified in the XML configuration file.</li>
+ <li><a href="./api/velosurf/sql/package-summary.html"><code>velosurf.sql</code></a> contains all the classes dealing with the database itself
+ via jdbc.</li>
+ <li><a href="./api/velosurf/util/package-summary.html"><code>velosurf.util</code></a> contains various utilities and helpers.</li>
+ <li><a href="./api/velosurf/validation/package-summary.html"><code>velosurf.validation</code></a> contains all classes related to data validation.</li>
+ <li><a href="./api/velosurf/web/package-summary.html"><code>velosurf.web</code></a> contains the two classes that can be used as
+ Velocity-tools tools: HttpQueryTool and VelosurfTool.</li>
+ <li><a href="./api/velosurf/web/auth/package-summary.html"><code>velosurf.web.auth</code></a> contains all classes related to authentication.</li>
+ <li><a href="./api/velosurf/web/l10n/package-summary.html"><code>velosurf.web.l10n</code></a> contains all classes related to localization.</li>
+ </ul>
+ <p>The next diagram shows the dependency relationships between the main classes of Velosurf. It should
+ be a good introduction for someone willing to browse the api or to dig into the sources.</p>
+ <img src="./class-diagram.png">
+ <p>Some dependencies are not shown to lighten the diagram:</p>
+ <ul>
+ <li>almost all objects of the <code>model</code> and <code>context</code> packages use the <code>PooledPreparedStatement</code> class, and many
+ use the <code>Database</code> class
+ <li>the <code>Database</code> class itself references many classes of the <code>model</code> and <code>context</code> packages
+ </ul>
+ </td>
+ </tr>
+
+</div>
+</div>
+
+
+ </body>
+
+</html>
Added: velocity/sandbox/velosurf/docs/class-diagram.png
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/class-diagram.png?rev=1298906&view=auto
==============================================================================
Binary file - no diff available.
Propchange: velocity/sandbox/velosurf/docs/class-diagram.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: velocity/sandbox/velosurf/docs/class-diagram.sxd
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/class-diagram.sxd?rev=1298906&view=auto
==============================================================================
Binary file - no diff available.
Propchange: velocity/sandbox/velosurf/docs/class-diagram.sxd
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: velocity/sandbox/velosurf/docs/configuration.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/configuration.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/configuration.html (added)
+++ velocity/sandbox/velosurf/docs/configuration.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,913 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>Velosurf - Configuration</title>
+
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+
+</head>
+
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><b>Configuration</b></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+</div>
+<div id="body">
+<h1>Configuration Reference</h1>
+<p>This page gives the reference of the Velosurf configuration file syntax.</p>
+<p><i>Don't be confused here, 'entity' and 'attribute' are both used as XML concepts and velosurf concepts... The velosurf entity has a corresponding XML element, the velosurf attribute has a corresponding XML element as well, and both have XML attributes.
+</i></p>
+<p>The configuration file follows <a href="./dtd.html">this DTD</a>.</p>
+<p>In brief:</p>
+<p><ul>
+<li>the <code><database></code> tag is the root element and must provide connection credentials (unless gathered in a <code><credentials></code> tag) and an optional schema name. It can contains any number of <code><entity></code>, <code><scalar></code>, <code><row></code>, <code><rowset></code> and <code><action></code> tags. Attributes and actions defined at this level are qualified as <i>root</i> attributes and actions. Note that you can also specify the username and password within the JDBC url.
+<li>Gathering the credentials (user, password and url) in a <code><credentials></code> tag, in conjunction with the use of xinclude, allows to put them in an external file (typically unversionned - very useful to change credetials in different instances of the same webapp). Note that driver and schema can also be specified in the <code><credentials></code> tag.</li>
+<li>If present, the root action named <code>startup</code> is executed when Velosurf is initialized.</li>
+<li><code><entity></code> tags usually correspond to a table (but not necessarily). They can contain any number of <code><scalar></code>, <code><row></code>, <code><rowset></code>, <code><action></code> and <code><constraint></code> tags.</li>
+<li><code><scalar></code>, <code><row></code> and <code><rowset></code> tags describe a custom entity attribute. Their content is an SQL query where entity columns and other <i>external parameters</i> appear as embedded tags. Their result is respectively a scalar, a row and a rowset.</li>
+<li><code><action></code> tags contain one or several SQL queries where entity columns and other <i>external parameters</i> appear as embedded tags. They return the number of affected rows.</li>
+<li><code><constraint></code> tags gather all the constraints applying to one column input value. Each constraint has a short syntax form (an XML attribute of the <code><constraint></code> tag) and an equivalent long syntax form (a child tag) that allows one to customize the error message of the constraint. <i>Warning: the Data Validation module is not actively maintained and could become deprecated or evolve in something else.</i></li>
+</ul></p>
+<p>The following table describes the meaning of all XML attributes per XML entity.</p>
+
+<table>
+<tbody>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><database> element (no parent)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ <tr align="center">
+ <td>database</td>
+
+ <td>user</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in the JDBC URL or in a <code><credentials></code> tag)</b></td>
+ <td>database account login</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+
+ <td>password</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in the JDBC URL or in a <code><credentials></code> tag)</b></td>
+ <td>database account password</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+
+ <td>url</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in a <code><credentials></code> tag)</b></td>
+ <td>database URL</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>driver</td>
+ <td><i> java_class_name</i></td>
+ <td>(none)</td>
+ <td>database driver class - if not specified, Velosurf will try to deduce it from the database URL</td>
+ </tr>
+ <tr align="center">
+
+ <td>database</td>
+ <td>schema</td>
+ <td><i>string</i></td>
+ <td>(none)</td>
+ <td>schema used, if any</td>
+ </tr>
+
+ <tr align="center">
+ <td>database</td>
+ <td>read-only</td>
+ <td>yes | no | true | false</td>
+ <td>yes</td>
+
+ <td>entities default access mode, read-only or read-write</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>caching</td>
+ <td>none | soft | full</td>
+
+ <td>none</td>
+ <td>default entities caching method (see caching attribute for entities)</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>case</td>
+ <td>sensitive | uppercase | lowercase</td>
+ <td>(driver-dependant)</td>
+ <td>case-sensivity policy used by Velosurf: sensitive, uppercase or lowercase<a href="#1"><sup>(1)</sup></a></td>
+ </tr>
+
+ <tr align="center">
+ <td>database</td>
+ <td>reverse</td>
+ <td>none | partial | tables | full</td>
+
+ <td>full</td>
+ <td>degree of reverse engineering: in 'partial' mode, only the tables corresponding to entities listed in the configuration file are reverse engineered - in 'full' mode, all tables and foreign keys are reverse engineered</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>loglevel</td>
+ <td>trace | debug | info | warn | error | fatal</td>
+
+ <td>info</td>
+ <td>logging level, from the most verbose to the less verbose</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>min-connections</td>
+ <td><i>integer</i></td>
+ <td>1</td>
+ <td>the initial number of connections in the connection pool</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>max-connections</td>
+ <td><i>integer</i></td>
+
+ <td>50</td>
+ <td>the maximum number of connections in the connection pool</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>seed</td>
+ <td><i>string</i></td>
+ <td>database url</td>
+ <td>seed of the encryption engine random generator</td>
+ </tr>
+ <tr align="center">
+ <td>database</td>
+ <td>check-connections</td>
+ <td>yes | no</td>
+ <td>yes</td>
+ <td>states whether connections are checked (and re-opened if necessary) before every statement execution</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><credentials> element (optional child of <database> used to gather credentials)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ <tr align="center">
+ <td>credentials</td>
+ <td>user</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in the JDBC URL or in the <code><database></code> tag)</b></td>
+ <td>database account login</td>
+ </tr>
+ <tr align="center">
+ <td>credentials</td>
+ <td>password</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in the JDBC URL or in the <code><database></code> tag)</b></td>
+ <td>database account password</td>
+ </tr>
+ <tr align="center">
+ <td>credentials</td>
+ <td>url</td>
+ <td><i>string</i></td>
+ <td><b>(required unless specified in the <code><database></code> tag)</b></td>
+ <td>database URL</td>
+ </tr>
+ <tr align="center">
+ <td>credentials</td>
+ <td>driver</td>
+ <td><i> java_class_name</i></td>
+ <td>(none)</td>
+ <td>database driver class - if not specified, Velosurf will try to deduce it from the database URL</td>
+ </tr>
+ <tr align="center">
+
+ <td>database</td>
+ <td>schema</td>
+ <td><i>string</i></td>
+ <td>(none)</td>
+ <td>schema used, if any</td>
+ </tr>
+
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><entity> element (child of <database>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+
+ <tr align="center">
+ <td>entity</td>
+ <td>name</td>
+ <td><i>string </i></td>
+
+ <td><b>(required)</b></td>
+ <td>entity name; if it is the name of an existing table, the columns of the table will automatically become attributes of this entity</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>table</td>
+ <td><i>string </i></td>
+
+ <td>entity name</td>
+ <td>use this attribute if the table name and the entity name are to be different</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>read-only</td>
+ <td>yes | no</td>
+ <td>yes</td>
+ <td>access mode, read-only or read-write</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>class</td>
+ <td><i>java_class_name</i></td>
+
+ <td>velosurf.context.Instance</td>
+ <td>java class used to map an instance of this entity</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>caching</td>
+ <td>none | soft | full</td>
+ <td>(none)</td>
+ <td>caching method: none, soft (automatic with respect to memory) or full (only cleared on <i>Entity.clearCache()</i> calls)</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>obfuscate</td>
+ <td><i>column </i>[,<i>column</i>...]</td>
+ <td>(none)</td>
+ <td>columns that will be obfuscated</td>
+ </tr>
+ <tr align="center">
+ <td>entity</td>
+ <td>localize</td>
+ <td><i>column </i>[,<i>column</i>...]</td>
+ <td>(none)</td>
+ <td>columns that will be localized</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><scalar> element (child of <entity>, or of <database> for root attributes)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>scalar</td>
+ <td>name</td>
+ <td> <i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>attribute name, can overload an existing column</td>
+ </tr>
+ <tr align="center">
+ <td>scalar</td>
+
+ <td>caching</td>
+ <td>yes | no</td>
+ <td>no</td>
+ <td>whether or not this scalar attribute should be cached</td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><row> element (child of <entity>, or of <database> for root attributes)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>row</td>
+ <td>name</td>
+ <td> <i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>attribute name, can overload an existing column</td>
+ </tr>
+ <tr align="center">
+ <td>row</td>
+
+ <td>result</td>
+ <td><i>entity</i></td>
+ <td>(none)</td>
+ <td>resulting entity, if any, so that other attributes can be called on the result.</td>
+ </tr>
+ <tr align="center">
+ <td>row</td>
+
+ <td>caching</td>
+ <td>yes | no</td>
+ <td>no</td>
+ <td>whether or not this row attribute should be cached</td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><rowset> element (child of <entity>, or of <database> for root attributes)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>rowset</td>
+ <td>name</td>
+ <td> <i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>attribute name, can overload an existing column</td>
+ </tr>
+ <tr align="center">
+ <td>rowset</td>
+ <td>result</td>
+ <td><i>entity</i></td>
+ <td>(none)</td>
+ <td>resulting entity, if any, so that other attributes can be called on the result.</td>
+ </tr>
+ <tr align="center">
+ <td>rowset</td>
+
+ <td>caching</td>
+ <td>yes | no</td>
+ <td>no</td>
+ <td>whether or not this rowset attribute should be cached</td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><aliases> element (child of <entity>)</big></td></tr>
+ <tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>aliases</td>
+ <td><i>string</i></td>
+ <td><i>string</i></td>
+ <td>(required)</td>
+ <td>define all aliases for this entity - for instance: <code><aliases alias_1='column_1' alias_2='column_2' ... /></code></td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><imported-key> element (child of <entity>)</big></td></tr>
+ <tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>imported-key</td>
+ <td>name</td>
+ <td><i>string</i></td>
+ <td>(required)</td>
+ <td>name given to the relationship</td>
+ </tr>
+ <tr align="center">
+ <td>imported-key</td>
+ <td>entity</td>
+ <td><i>string</i></td>
+ <td>(required)</td>
+ <td>name of the entity corresponding to the foreign table</td>
+ </tr>
+ <tr align="center">
+ <td>imported-key</td>
+ <td>foreign-cols</td>
+ <td><i>col</i> [ , <i>col</i>... ]</td>
+ <td>(required)</td>
+ <td>comma-separated list of the local columns matching the key columns of the foreign table</td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><exported-key> element (child of <entity>)</big></td></tr>
+ <tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>exported-key</td>
+ <td>name</td>
+ <td><i>string</i></td>
+ <td>(required)</td>
+ <td>name given to the relationship</td>
+ </tr>
+ <tr align="center">
+ <td>exported-key</td>
+ <td>entity</td>
+ <td><i>string</i></td>
+ <td>(required)</td>
+ <td>name of the entity corresponding to the foreign table</td>
+ </tr>
+ <tr align="center">
+ <td>exported-key</td>
+ <td>foreign-cols</td>
+ <td><i>col</i> [ , <i>col</i>... ]</td>
+ <td>(required)</td>
+ <td>comma-separated list of the foreign columns matching the key columns of the local table</td>
+ </tr>
+
+ <tr align="center">
+ <td>exported-key</td>
+ <td>order</td>
+ <td><i>col</i> [ , <i>col</i>... ]</td>
+ <td>(none)</td>
+ <td>comma-separated list of the foreign columns by which the result should be ordered</td>
+ </tr>
+
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><action> element (child of <entity>, or of <database> for root actions)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr align="center">
+ <td>action</td>
+ <td>name</td>
+ <td><i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>Action name. If present, the root <code>startup</code> action is performed when Velosurf is initialized.</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+ <tr><td colspan="5" style="background:white;font-size:14px;text-align:center;">The following tags belong to the data validation module.</td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><constaint> element (child of <entity>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>column</td>
+ <td><i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>name of this entity's column the constraint is to be applied to</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>type</td>
+ <td>integer | number | date | email</td>
+ <td>(none)</td>
+ <td>expected data type - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>min-len</td>
+ <td><i>positive integer</i></td>
+ <td>(none)</td>
+ <td>minimum length - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>max-len</td>
+ <td><i>positive integer</i></td>
+ <td>(none)</td>
+ <td>maximum length - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>min</td>
+ <td><i>integer</i></td>
+ <td>(none)</td>
+ <td>minimum value (implies 'number' data type if none specified) - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>max</td>
+ <td><i>integer</i></td>
+ <td>(none)</td>
+ <td>maximum value (implies 'number' data type if none specified) - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>after</td>
+ <td><i>YYYYMMDD</i></td>
+ <td>(none)</td>
+ <td>data must be a date >= this value (implies 'date' type if none specified) - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>before</td>
+ <td><i>YYYYMMDD</i></td>
+ <td>(none)</td>
+ <td>data must be a date <= this value (implies 'date' type if none specified) - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>not-empty</td>
+ <td>true | false</td>
+ <td>false</td>
+ <td>data must not be null or empty - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>not-null</td>
+ <td>true | false</td>
+ <td>false</td>
+ <td>data must not be null - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>one-of</td>
+ <td><i>value</i>[,<i>value</i>...]</td>
+ <td>false</td>
+ <td>data must be one of the supplied values - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>reference</td>
+ <td><i>table.column</i></td>
+ <td>(none)</td>
+ <td>data must be present in <i>table.column</i> - short syntax</td>
+ </tr>
+ <tr>
+ <td>constraint</td>
+ <td>regex</td>
+ <td><i>pattern</i></td>
+ <td>(none)</td>
+ <td>data must follow the provided pattern - short syntax</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><integer> element (child of <constaint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>integer</td>
+ <td>min</td>
+ <td><i>integer</i></td>
+ <td>(none)</td>
+ <td>minimum value - long syntax</td>
+ </tr>
+ <tr>
+ <td>integer</td>
+ <td>max</td>
+ <td><i>integer</i></td>
+ <td>(none)</td>
+ <td>maximum value - long syntax</td>
+ </tr>
+ <tr>
+ <td>integer</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not in the valid range</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><number> element (child of <constaint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>number</td>
+ <td>min</td>
+ <td><i>number</i></td>
+ <td>(none)</td>
+ <td>minimum value - long syntax</td>
+ </tr>
+ <tr>
+ <td>number</td>
+ <td>max</td>
+ <td><i>number</i></td>
+ <td>(none)</td>
+ <td>maximum value - long syntax</td>
+ </tr>
+ <tr>
+ <td>number</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not in the valid range</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><min-len> element (child of <constaint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>min-len</td>
+ <td>value</td>
+ <td><i>positive integer</i></td>
+ <td><b>(required)</b></td>
+ <td>minimum length - long syntax</td>
+ </tr>
+ <tr>
+ <td>min-len</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not in the valid range</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><max-len> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>max-len</td>
+ <td>value</td>
+ <td><i>positive integer</i></td>
+ <td><b>(required)</b></td>
+ <td>maximum length - long syntax</td>
+ </tr>
+ <tr>
+ <td>max-len</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not in the valid range</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><date> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>date</td>
+ <td>after</td>
+ <td><i>YYYYMMDD</i></td>
+ <td>(none)</td>
+ <td>data must be a date >= this value - long syntax</td>
+ </tr>
+ <tr>
+ <td>date</td>
+ <td>before</td>
+ <td><i>YYYYMMDD</i></td>
+ <td>(none)</td>
+ <td>data must be a date <= this value - long syntax</td>
+ </tr>
+ <tr>
+ <td>date</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not a valid date or is outside range</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><email> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>email</td>
+ <td>check-dns</td>
+ <td>true | false</td>
+ <td>false</td>
+ <td>whether to issue a DNS lookup query to check the validity of the email</td>
+ </tr>
+ <tr>
+ <td>email</td>
+ <td>check-smtp</td>
+ <td>true | false</td>
+ <td>false</td>
+ <td>whether to issue an SMTP login to check the validity of the email</td>
+ </tr>
+ <tr>
+ <td>email</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: '{1}' is not a valid email</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><not-null> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>not-null</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0} cannot be null</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><not-empty> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>not-empty</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0} cannot be empty</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><one-of> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>one-of</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: value '{1}' must be one of: <i>value</i>,...</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><value> element (child of <one-of>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ <td>specifies a value for the long syntax form of the <one-of> constraint (text content)</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><reference> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>reference</td>
+ <td>foreign-key</td>
+ <td><i>table.column</i></td>
+ <td><b>(required)</b></td>
+ <td>data must be present in <i>table.column</i> - long syntax</td>
+ </tr>
+ <tr>
+ <td>reference</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: value '{1}' not found in <i>table.column</i></td>
+ <td>message to display when constraint fails</td>
+ </tr>
+ <tr><td colspan="5" style="background:white;"></td></tr>
+<tr style="margin-top:8px; font-weight:bold;"><td colspan=5 align=center><big><regex> element (child of <constraint>)</big></td></tr>
+<tr align="center">
+ <td><b>XML element</b></td>
+ <td><b>XML attribute</b></td>
+ <td><b>syntax</b></td>
+ <td><b>default value</b></td>
+ <td><b>meaning</b></td>
+ </tr>
+ <tr>
+ <td>regex</td>
+ <td>pattern</td>
+ <td><i>string</i></td>
+ <td><b>(required)</b></td>
+ <td>data must follow the provided pattern - long syntax</td>
+ </tr>
+ <tr>
+ <td>regex</td>
+ <td>message</td>
+ <td><i>string</i></td>
+ <td>field {0}: value '{1}' is not valid</td>
+ <td>message to display when constraint fails</td>
+ </tr>
+</tbody>
+</table>
+<a name='1'/>
+<p><b>(1)</b> This case-sensivity parameter indicates the policy that Velosurf must follow with SQL keywords (tables and columns)
+when speaking with the relational database. It should mimic the behaviour the database engine has with its metadata tables,
+and the default is chosen depending on the database vendor when known (see <a href='api/velosurf/sql/DriverInfo.html'>DriverInfo.java</a>). It is one of:
+<ul>
+<li><code>sensitive</code>: It does not necessarily mean that the database is case-sensitive,
+only that Velosurf won't issue any conversion.
+<li><code>uppercase</code>: Entities and attributes are case-insensitive; all identifiers will be stored
+internally and passed to the JDBC driver as uppercase strings
+(references in templates and names in the configuration file are then case-insensitive).
+<li><code>lowercase</code>: Same as above, lowercase.
+</ul>
+It doesn't impact case of identifiers used in the configuration file or in the templates. Those ones are converted
+to lowercase by default and this behaviour can be changed via the <code>velosurf.case</code> Java system property.</p>
+</p>
+</div>
+</div>
+ </body>
+
+</html>
+
+
+
+
+
+
Added: velocity/sandbox/velosurf/docs/download.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/download.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/download.html (added)
+++ velocity/sandbox/velosurf/docs/download.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,133 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>Velosurf - Download</title>
+
+
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+
+</head>
+
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><b>Download</b>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+</div>
+<div id="body">
+<h1>Velosurf 2.x</h1>
+<p>The latest release is <a href="http://prdownloads.sourceforge.net/velosurf/velosurf-2.3.tgz?download">Velosurf 2.3</a> (gzipped tar archive). It contains both the binary and the sources.</p>
+<p>Velosurf 2.x need Java 1.5. If you're still using an older Java version, consider
+using a Velosurf 1.4.x release.</p>
+<p>If you are upgrading from a 1.4.x release and using Velosurf inside a Velocity Tools webapp, be sure to upgrade your
+version of <code>velocity-tools-view</code> and to change the deprecated classname <code>velosurf.tools.VelosurfTool</code> to
+the new <code>velosurf.web.VelosurfTool</code> inside <code>toolbox.xml</code>.</p>
+<p>The dependency jars are not included in the archive. To automatically download them,
+if you have <a href="http://ant.apache.org/">Apache Ant</a> installed, go into the <code>build/</code>
+directory of the extracted archive and type <code>ant download</code>. This will download all dependency jars
+into the <code>./lib/</code> directory. Other ant tasks will download any needed jars as well. Or you can fetch them individually from the links bellow:</p>
+<ul>
+<li>Dependencies needed to build velosurf:
+<ul>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/commons-lang/commons-lang/2.3/commons-lang-2.3.jar">commons-lang-2.3.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/commons-net/commons-net/1.4.1/commons-net-1.4.1.jar">commons-net-1.4.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/org/jdom/jdom/1.1.2/jdom-1.1.2.jar">jdom-1.1.2.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/servletapi/servletapi/2.4/servletapi-2.4.jar">servletapi-2.4.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/org/apache/velocity/velocity/1.7/velocity-1.7.j">velocity-1.7.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/org/apache/velocity/velocity-tools/2.0/velocity-tools-2.0.jar">velocity-tools-2.0.jar</a></li>
+</ul>
+</li>
+<li>Dependencies needed at runtime:
+<ul>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/commons-beanutils/commons-beanutils/1.7.0/commons-beanutils-1.7.0.jar">commons-beanutils-1.7.0.jar</a> (needed by Velocity Tools)</li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/commons-collections/commons-collections/3.2/commons-collections-3.2.jar">commons-collections-3.2.jar</a> (needed by Velocity)</li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/commons-digester/commons-digester/1.8/commons-digester-1.8.jar">commons-digester-1.8.jar</a> (needed by Velocity Tools)</li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/crimson/crimson/1.1.3/crimson-1.1.3.jar">crimson-1.1.3.jar</a> (needed by JDOM)</li>
+</ul>
+</li>
+<li>Dependancies needed to run testcases:
+<ul>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/org/hsqldb/hsqldb/2.2.8/hsqldb-2.2.8.jar">hsqldb-2.2.8.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/httpunit/httpunit/1.6.1/httpunit-1.6.1.jar">httpunit-1.6.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/rhino/js/1.6R5/js-1.6R5.jar">js-1.6R5.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/junit/junit/4.3/junit-4.3.jar">junit-4.3.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/nekohtml/nekohtml/0.9.5/nekohtml-0.9.5.jar">nekohtml-0.9.5.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/xerces/xercesImpl/2.8.1/xercesImpl-2.8.1.jar">xercesImpl-2.8.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/xerces/xmlParserAPIs/2.6.2/xmlParserAPIs-2.6.2.jar">xmlParserAPIs-2.6.2.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/jetty/jetty/6.0.1/jetty-6.0.1.jar">jetty-6.0.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/jetty/jetty-util/6.0.1/jetty-util-6.0.1.jar">jetty-util-6.0.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/jetty/servlet-api/2.5-6.0.1/servlet-api-2.5-6.0.1.jar">servlet-api-2.5-6.0.1.jar</a></li>
+<li><a href="http://mirrors.ibiblio.org/pub/mirrors/maven2/jetty/start/6.0.1/start-6.0.1.jar">start-6.0.1.jar</a></li>
+</ul>
+</li>
+</ul>
+<p>Some earlier versions of the <code>commons-*</code> libraries may be supported by Velosurf. To test them,
+you can edit the version numbers in the <code>./build/build.properties</code> file and test Velosurf with '<code>ant test</code>'.</p>
+<p>Running the tests also requires some additionnal libraries which will be downloaded when needed.</p>
+<p>You can also checkout the last sources from the subversion repository with the following command:</p>
+<p><code>svn co https://svn.apache.org/repos/asf/velocity/sandbox velosurf</code></p>
+<h1>Velosurf 1.4.x</h1>
+<p>The Velosurf 1.4.x releases are not anymore maintained but they are still here if you cannot use java 1.5.</p>
+<p>The latest release is <a href="http://prdownloads.sourceforge.net/velosurf/velosurf-1.4.4.tgz?download">Velosurf 1.4.4</a>. (gzipped tar archive). It contains both the binary and the sources,
+plus all dependency jars in the <code>lib/</code> directory. The binary is in the <code>bin/</code> directory of the extracted archive.</p>
+<p>You can also checkout the last 1.4.x sources from the SourceForge CVS repository with the following commands:</p>
+<p><code>cvs -d:pserver:anonymous@velosurf.cvs.sf.net:/cvsroot/velosurf login<br><br>
+cvs -z3 -d:pserver:anonymous@velosurf.cvs.sf.net:/cvsroot/velosurf co -P velosurf</code></p>
+</div>
+</body>
+</html>
Added: velocity/sandbox/velosurf/docs/dtd.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/dtd.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/dtd.html (added)
+++ velocity/sandbox/velosurf/docs/dtd.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,150 @@
+<html>
+<head>
+<title>Velosurf Config File DTD</title>
+ <link rel="stylesheet" href="file:///home/claude/projects/velosurf/docs/velosurf.css" type="text/css">
+</head>
+<body>
+<p><i>You can also <a href="./velosurf.dtd">download the dtd</a></i></p>
+<div class="source"><xmp>
+<!ELEMENT database (credentials?,entity*,scalar*,row*,rowset*,action*)>
+
+<!ATTLIST database user CDATA #IMPLIED>
+<!ATTLIST database password CDATA #IMPLIED>
+<!ATTLIST database url CDATA #IMPLIED>
+<!ATTLIST database driver CDATA #IMPLIED>
+<!ATTLIST database schema CDATA #IMPLIED>
+<!ATTLIST database read-only ( yes | no ) "yes">
+<!ATTLIST database caching ( none | soft | full ) "none">
+<!ATTLIST database reverse ( none | partial | full ) "full">
+<!ATTLIST database case ( sensitive | uppercase | lowercase ) #IMPLIED>
+<!ATTLIST database loglevel ( trace | debug | info | warn | error ) "info">
+<!ATTLIST database min-connections CDATA #IMPLIED>
+<!ATTLIST database max-connections CDATA #IMPLIED>
+<!ATTLIST database seed CDATA #IMPLIED>
+
+<!ELEMENT credentials>
+
+<!ATTLIST database user CDATA #IMPLIED>
+<!ATTLIST database password CDATA #IMPLIED>
+<!ATTLIST database url CDATA #IMPLIED>
+<!ATTLIST database driver CDATA #IMPLIED>
+<!ATTLIST database schema CDATA #IMPLIED>
+
+<!ELEMENT entity (scalar*,row*,rowset*,action*,constraint*)>
+
+<!ATTLIST entity name CDATA #REQUIRED>
+<!ATTLIST entity table CDATA #IMPLIED>
+<!ATTLIST entity read-only ( yes | no ) "yes">
+<!ATTLIST entity class CDATA #IMPLIED>
+<!ATTLIST entity caching ( none | soft | full) "none">
+<!ATTLIST entity obfuscate CDATA #IMPLIED>
+<!ATTLIST entity localized CDATA #IMPLIED>
+
+<!ELEMENT scalar (#PCDATA)> <!-- where #PCDATA is an SQL query with column tags -->
+
+<!ATTLIST scalar name CDATA #REQUIRED>
+<!ATTLIST scalar caching CDATA "no">
+
+<!ELEMENT row (#PCDATA)> <!-- where #PCDATA is an SQL query with column tags -->
+
+<!ATTLIST row name CDATA #REQUIRED>
+<!ATTLIST row result CDATA #IMPLIED>
+<!ATTLIST scalar caching CDATA "no">
+
+<!ELEMENT rowset (#PCDATA)> <!-- where #PCDATA is an SQL query with column tags -->
+
+<!ATTLIST rowset name CDATA #REQUIRED>
+<!ATTLIST rowset result CDATA #IMPLIED>
+<!ATTLIST scalar caching CDATA "no">
+
+<!ELEMENT imported-key>
+
+<!ATTLIST imported-key name CDATA #REQUIRED>
+<!ATTLIST imported-key entity CDATA #REQUIRED>
+<!ATTLIST imported-key foreign-cols CDATA #REQUIRED>
+
+<!ELEMENT exported-key>
+
+<!ATTLIST exported-key name CDATA #REQUIRED>
+<!ATTLIST exported-key entity CDATA #REQUIRED>
+<!ATTLIST exported-key foreign-cols CDATA #REQUIRED>
+
+<!ELEMENT action (#PCDATA)> <!-- where #PCDATA is an SQL query (or a set of queries) with column tags -->
+
+<!ATTLIST action name CDATA #REQUIRED>
+
+<!ELEMENT constraint (email?,min-len?,max-len?,integer?,number?,date?,not-null?,not-empty?,one-of?,reference?,regex?)>
+
+<!ATTLIST constraint column CDATA #REQUIRED>
+<!ATTLIST constraint type ( integer | number | date | email ) #IMPLIED>
+<!ATTLIST constraint min-len CDATA #IMPLIED>
+<!ATTLIST constraint max-men CDATA #IMPLIED>
+<!ATTLIST constraint min CDATA #IMPLIED>
+<!ATTLIST constraint max CDATA #IMPLIED>
+<!ATTLIST constraint after CDATA #IMPLIED>
+<!ATTLIST constraint before CDATA #IMPLIED>
+<!ATTLIST constraint not-empty CDATA #IMPLIED>
+<!ATTLIST constraint not-null CDATA #IMPLIED>
+<!ATTLIST constraint one-of CDATA #IMPLIED>
+<!ATTLIST constraint reference CDATA #IMPLIED>
+<!ATTLIST constraint regex CDATA #IMPLIED>
+
+<!ELEMENT email>
+
+<!ATTLIST email dns-check ( yes | no ) "no">
+<!ATTLIST email sptm-check ( yes | no ) "no">
+<!ATTLIST email message CDATA #IMPLIED>
+
+<!ELEMENT min-len>
+
+<!ATTLIST min-len value CDATA #REQUIRED>
+<!ATTLIST min-len message CDATA #IMPLIED>
+
+<!ELEMENT max-len>
+
+<!ATTLIST max-len value CDATA #REQUIRED>
+<!ATTLIST max-len message CDATA #IMPLIED>
+
+<!ELEMENT integer>
+
+<!ATTLIST integer min CDATA #IMPLIED>
+<!ATTLIST integer max CDATA #IMPLIED>
+<!ATTLIST integer message CDATA #IMPLIED>
+
+<!ELEMENT number>
+
+<!ATTLIST number min CDATA #IMPLIED>
+<!ATTLIST number max CDATA #IMPLIED>
+<!ATTLIST number message CDATA #IMPLIED>
+
+<!ELEMENT date>
+
+<!ATTLIST date before CDATA #IMPLIED>
+<!ATTLIST date after CDATA #IMPLIED>
+<!ATTLIST date message CDATA #IMPLIED>
+
+<!ELEMENT not-null>
+
+<!ATTLIST not-null message CDATA #IMPLIED>
+
+<!ELEMENT not-empty>
+
+<!ATTLIST not-empty message CDATA #IMPLIED>
+
+<!ELEMENT one-of (value+)>
+
+<!ATTLIST one-of message CDATA #IMPLIED>
+
+<!ELEMENT value (#PCDATA)>
+
+<!ELEMENT reference>
+
+<!ATTLIST reference foreign-key CDATA #REQUIRED>
+<!ATTLIST reference message CDATA #IMPLIED>
+
+<!ELEMENT regex>
+
+<!ATTLIST regex pattern CDATA #REQUIRED>
+<!ATTLIST regex message CDATA #IMPLIED>
+</xmp></div>
+</body>
Added: velocity/sandbox/velosurf/docs/faq.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/faq.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/faq.html (added)
+++ velocity/sandbox/velosurf/docs/faq.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,167 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+<title>Velosurf - FAQ</title>
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+</head>
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li><b>FAQ</b></li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<div id="body">
+<h1>Frequently Asked Questions</h1>
+<h2>Table of Content</h2>
+<ol>
+<li><a href="#general">General Questions</a></li>
+<ol>
+<li><a href="#general.what">What is Velosurf?</a></li>
+<li><a href="#general.howtouse">How do I use it?</a></li>
+<li><a href="#general.howitworks">How does it work?</a></li>
+</ol>
+<li><a href="#install">Installation, Configuration and Integration</a></li>
+<ol>
+<li><a href="#install.webapp">How do I use Velosurf within my Webapp?</a></li>
+<li><a href="#install.java">How do I use Velosurf within my Java application?</a></li>
+<li><a href="#install.ant">How do I use Velosurf with Ant?</a></li>
+<li><a href="#install.dvsl">How do I use Velosurf with DVSL?</a></li>
+<li><a href="#install.texen">How do I use Velosurf with Texen?</a></li>
+</ol>
+<li><a href="#sql">SQL Questions</a></li>
+<ol>
+<li><a href="#sql.keys">What about primary and foreign keys?</a></li>
+</ol>
+<li><a href="#mvc">Velosurf and the MVC Design Pattern</a></li>
+<ol>
+<li><a href="#mvc.def">What does MVC stand for?</a></li>
+<li><a href="#mvc.velosurf">Is Velosurf MVC-compliant?</a></li>
+<li><a href="#mvc.login">How to use different logins with different accesses to the database?</a></li>
+</ol>
+<li><a href="#troubleshooting">Troubleshooting</a></li>
+<ol>
+<li><a href="#troubleshooting.what">It doesn't work! What can I do?</a></li>
+<li><a href="#troubleshooting.hang">Velosurf connects to the database, but hangs right after, with no message. What is the problem?</a></li>
+</ol>
+</ol>
+<a name="general"/><h2>1. General Questions</h2>
+<a name="general.what"/><h3>1.1 What is Velosurf?</h3><div class="section"><p>Velosurf is a light and flexible Java library meant to expose a relational
+database to <a href="http://jakarta.apache.org/velocity">Jakarta Velocity</a> templates. Velosurf does an
+automatic reverse engineering of a database source and provides a default mapping that can then be extended
+and customized in many ways.</p></div>
+<a name="general.howtouse"/><h3>1.2 How do I use it?</h3><div class="section"><p> Velosurf provides the Velocity context with a <code>$db</code> tool object
+that is a starting point to access database tables and queries. An XML configuration file allows you
+to gather all SQL code in one place: Table columns and SQL queries are seen as standard properties
+from within the templates.</p></div>
+<a name="general.howitworks"/><h3>1.3 How does it work?</h3><div class="section"><p>At start, Velosurf reads the configuration file - that must at least
+contain database connection parameters - plus all SQL queries that define custom properties. Then it
+performs a reverse engineering of the database. Roughly speaking, tables and result sets are used as
+iterators in #foreach loops, and rows are seen as associative maps (that map a column / a query / a query
+field to their values).</p></div>
+<a name="install"/><h2>2. Installation, Configuration and Integration</h2>
+<a name="install.webapp"/><h3>2.1 How do I use Velosurf within my Webapp?</h3><div class="section"><p> All you need to do is to put an instance
+of velosurf.web.VelosurfTool into your Velocity context.
+The easiest way is to use the VelocityViewServlet
+class (or a subclass), provided with the <a href="http://jakarta.apache.org/velocity/tools/index.html">velocity-tools</a>
+subproject: it provides a generic plug-in mechanism enabling external tools to be automatically plugged
+into Velocity contexts, with scope considerations. Refer to the Installation page for more.</p></div>
+<a name="install.java"/><h3>2.2 How do I use Velosurf within my Java application?</h3><div class="section"><p> First, you must ensure that Velosurf will find
+its configuration file, as explained <a href="api/velosurf/Velosurf.html">here</a>. Then you just have
+to put an instance of <code>velosurf.Velosurf</code> in the Velocity context.</p></div>
+<a name="install.ant"/><h3>2.3 How do I use Velosurf with Ant?</h3><div class="section"><p>You will have to use VPP. Please have a look at the example provided
+in <code>example/ant-vpp</code> for how to proceed.</p></div>
+<a name="install.dvsl"/><h3>2.4 How do I use Velosurf with DVSL?</h3><div class="section"><p> Check the DVSL doc on how to create a toolbox.
+Then, include the line "<code>toolbox.tool.db=velosurf.standalone.Velosurf</code>" in your
+toolbox.props file, and have Velosurf find its velosurf.xml configuration file (see 2.2).</p></div>
+<a name="install.texen"/><h3>2.5 How do I use Velosurf with Texen?</h3><div class="section"><p> Put the line "<code>context.objects.db=velosurf.standalone.Velosurf</code>"
+in your <code>texen.properties</code> file, and have Velosurf find the velosurf.xml configuration file (see 2.2).</p></div>
+<a name="sql"/><h2>3. SQL Questions</h2>
+<a name="sql.keys"/><h3>3.1 What about primary and foreign keys?</h3><div class="section"><p> Primary keys are reverse engineered and used by Velosurf
+in all the <code>fetch</code> methods. Foreign-keys are also reverse engineered by default and produce each two attributes,
+one for the imported key and one for the exported key (e.g. $book.publisher and $publisher.books). You can then
+traverse foreign keys back and forth using the dot operator. See <a href="./user-guide.html#foreign-keys">this section</a> for more details.</p></div>
+<a name="mvc"/><h2>4. Velosurf and the MVC Design Pattern</h2>
+<a name="mvc.def"/><h3>4.1 What does MVC stand for?</h3><div class="section"><p> In brief, MVC stands for Model-View-Controller.
+It is an architecture design pattern that states that applications should be structured in three distinct
+layers, the Model (what your application modelizes), the View (typically Velocity) and the Controller
+(typically an ActionServlet or the like).</p></div>
+<a name="mvc.velosurf"/><h3>4.2 Is Velosurf MVC-compliant?</h3><div class="section"><p> Certainly! It implements the data model part,
+leaving you with the business logic part of the model. However, you must keep in mind that
+you should not modify data objects from within Velocity templates (you can use the Velosurf
+Java API or standard JDBC calls to achieve modifications, either from within your
+controller or from custom mapping classes).</p></div>
+<a name="mvc.login"/><h3>4.3 How to use different logins with different accesses to the database?</h3><div class="section"><p>Just have
+two different configuration files. You can factorize the model using the <xi:include> syntax.
+</p></div>
+<a name="troubleshooting"/><h2>5. Troubleshooting</h2>
+<a name="troubleshooting.problem"/><h3>5.1 It doesn"t work! What can I do?</h3><div class="section"><p> The first thing to do is to check the log. Chances are you'll find
+an exception and/or a message indicating the cause or the problem.</p></div>
+<a name="troubleshooting.hang"/><h3>5.2 Velosurf connects to the database, but hangs right after, with no message. What is the problem?</h3><div class="section"><p>
+Have you provided a schema name? Under Oracle for instance, there are so many system tables
+(several thousands) that the reverse engineering can be very long. You can also choose the
+"manual" reverse engineering option so that for instance only the entities listed in velosurf.xml
+are processed.</p></div>
+</p></div>
+<font size="+1">Got another question not listed here? <a href="http://velocity.apache.org/contact.html">Ask the mailing list</a>!</font></p
+</div>
+</div>
+
+</body>
+</html>
Added: velocity/sandbox/velosurf/docs/index.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/index.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/index.html (added)
+++ velocity/sandbox/velosurf/docs/index.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,156 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>Velosurf</title>
+
+
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+
+</head>
+
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://velocity.apache.org"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><b>Home</b></li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<div id="body">
+
+<h1>What is Velosurf?</h1>
+
+<div class="subsection">
+<p align="left">Velosurf is a java database mapping layer
+for <a href="http://velocity.apache.org">Apache
+Velocity</a>.</p>
+
+<p> Velosurf provides an 'out-of-the-box' automatized
+mapping of database tables and fields, along with the ability to easily
+define custom entities, queries and actions in SQL. It is a
+lightweight placeholder to persistence systems.</p>
+
+<p align="left">Velosurf main features are:</p>
+
+<ul>
+
+ <li>easy template grammar</li>
+
+ <li>code isolation: SQL queries are gathered in one place and
+appear as standard
+objects properties</li>
+
+ <li>dynamic mapping: no need to recompile on any database change</li>
+
+ <li>automatic connection recovery, statements and connections
+pooling</li>
+
+ <li>reverse engeenering of database schema</li>
+
+ <li>natural type mapping</li>
+
+ <li>transactions</li>
+
+ <li>default Java mapping objects that you can override when
+needed</li>
+
+ <li>basic tools to include authentication, internationalization
+and data validation in your app</li>
+
+</ul>
+
+<p>Velosurf can be used as a standard Velocity tool (and as such
+easily integrated in every Web framework that supports the Velocity
+Tools rendering layer), as well as a generic java database abstraction
+layer.</p>
+</div>
+<h1 align="left">Why Velosurf?</h1>
+<div class="subsection">
+<p align="left">The main goal of Velosurf is to spare
+template writers the pain of rewriting specific database mapping layers
+in Java for each project involving Velocity and database entities. It
+is also meant to have a clean separation between SQL, Java and VTL.</p>
+
+<p align="left">Persistence layers are hard to design and
+maintain, and have been made obsolete by database caching technology.
+So why not have a thin and generic mapping engine that will fetch
+values directly from the database when you need them? With Velosurf,
+object properties can represent not just column values, but also
+complex queries, something difficult to do with a persistence framework.</p>
+
+<p align="left">Last but not least: developers often try
+to protect users from many concepts that may appear too complex or too
+weird to them. But even if a data model is complex, its complexity has
+nothing or little to do with technical constraints, and everything to
+do with logic and modeling. The spirit of Velosurf is that those
+constraints should be shared and exposed to all people involved in a
+project - like designers - who should be as competent as developers are
+(who said "more"?) to deal with business logic.</p>
+
+<p align="left">In a nutshell, Velosurf allows developers
+to expose a data model where properties are table fields or SQL queries
+and designers to easily traverse this data model by means of the '.'
+dereferencement operator (e.g. "<code>book.publisher.address</code>").</p>
+</div>
+
+</div>
+
+</div>
+
+</body>
+</html>
Added: velocity/sandbox/velosurf/docs/installation.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/installation.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/installation.html (added)
+++ velocity/sandbox/velosurf/docs/installation.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,178 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+
+ <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+ <title>Velosurf - Installation</title>
+
+
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+
+</head>
+
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li> <a href="./overview.html">Overview</a>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><b>Installation</b></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<div id="body">
+<h1>Installation</h1>
+<p>This page details the setup of Velosurf in a Webapp powered by <a href="http://velocity.apache.org/tools/releases/1.4">Velocity Tools 1.4</a> or <a href="http://velocity.apache.org/tools/releases/2.0">Velocity Tools 2.0</a>.
+For other environments, you should refer to the <a href="./faq.html">FAQ</a> or the <a href="http://velocity.apache.org/contact.html">mailing list</a>.</p>
+<p>You should be familiar with Velocity and the concept of Webapp to easily understand the following.<br>
+<a name="building"></a></p>
+<h2>Building the Velosurf archive</h2>
+<p>The last release is included at the root of the archive directory, but if you want to re-build the library, you need to have <a href="http://jakarta.apache.org/ant/index.html">ant</a> installed.<br>
+<br>
+ Then, the <code>./build/build.xml</code> file contains the following ant targets:</p>
+ <ul>
+ <li><b>jar</b>: builds <code>./velosurf-<i>x</i>.<i>y</i>.jar</code></li>
+ <li><b>download</b>: downloads dependency jars in the <code>./lib directory</code></li>
+ <li><b>javadoc</b>: builds the javadocs in <code>./docs/api</code></li>
+ <li><b>tarball</b>: builds the distribution tarball <code>velosurf-<i>x</i>.<i>y</i>.tgz</code>
+ <li><b>test</b>: runs all the test cases.</li>
+ <li><b>clean</b></b>: cleans all temporary files.</li>
+ <li><b>clean-all</b>: cleans all temporary files and deletes all dependency jars.</li>
+ </ul>
+ <p><a name="toolbox"></a></p>
+ <h2>Configuring the toolbox</h2>
+ <p>First, you need to set up the Velocity toolbox in your Webapp. Please refer to <a hef="http://velocity.apache.org/tools/releases/1.4/view/index.html#Installation">VelovityView Tools 1.4 installation</a>
+ or to <a href="http://velocity.apache.org/tools/devel/view.servlet.html">VelocityView 2.0+ installation</a>.
+ </p>
+<p>Then, you have to set up the Velosurf tools by means of the <code>/WEB-INF/toolbox.xml</code> (for 1.4):</p>
+<div class="source"><pre><?xml version="1.0"?>
+<toolbox> <!-- toolbox file for Velocity View 1.4 -->
+
+ <!-- ...other tools... -->
+
+ <!-- http query parameters tool:
+ You can either use org.apache.velocity.tools.view.tools.ParameterParser
+ or velosurf.web.HttpQueryTool, which inherits the former to add a generic
+ setter - in clear, if using VelocityTools 1.4 or prior, you have to use
+ the Velosurf version if you want to be able to add values to the tool
+ like with #set($query.foo='bar').-->
+
+ <tool>
+ <key>query</key>
+ <scope>request</scope>
+ <class>velosurf.web.HttpQueryTool</class>
+ </tool>
+
+ <!-- database -->
+
+ <tool>
+ <key>db</key>
+ <scope>request</scope>
+ <class>velosurf.web.VelosurfTool</class>
+ <-- uncomment the next line tu use a custom model file -->
+ <--<param name='config' value='./WEB-INF/mymodel.xml'/>-->
+ </tool>
+
+</toolbox></pre></div>
+
+<p>Or <code>/WEB-INF/tools.xml</code> (for 2.0+):</p>
+
+<div class="source"><pre><?xml version="1.0"?>
+ <tools> <!-- toolbox file for Velocity View 2.0+ -->
+
+ <!-- ... other toolboxes ... -->
+
+ <toolbox scope="request"/> <!-- or other scopes, see below -->
+ <!-- ... other tools ... -->
+ <tool key="db" class="velosurf.web.VelosurfTool"/> <!-- add «config="/WEB-INF/mymodel.xml"» for a custom model file -->
+ </toolbox>
+
+ </toolbox></pre></div>
+
+ <p>Notes:</p>
+ <p>
+ <ul>
+ <li>by default, Velosurf searches for its model in <code>/WEB-INF/model.xml</code> or <code>/WEB-INF/model.xml</code></li>
+ <li>you can use as many database tools as you wish (you may then use custom model filenames)</li>
+ <li>the <code>velosurf.web.VelosurfTool</code> object is a tiny wrapper that doesn't introduce any overhead
+ when instanciated for each request, but you may choose to use it in a session or application scope if you do not use
+ per-request refinements or orderings.</li>
+ </ul>
+ </p>
+
+<p>Alternatively, the name of the configuration file can also be specified in the <code>velosurf.config</code> servlet context parameter
+(this latter method must be chosen when using Velosurf authentication or localization filters that rely on the database since the toolbox
+is not yet initialized at the time the filters are initialized). In that case, you'll have to put the following declaration in <code>/WEB-INF/web.xml</code>:</p>
+<div class="source"><xmp> <context-param>
+ <param-name>velosurf.config</param-name>
+ <param-value>/WEB-INF/db.xml</param-value>
+ </context-param></xmp></div>
+
+ <h2>Configuring the Velosurf model</h2>
+ <p>By default, the database will be reverse engineered and each table becomes an entity, each column an attribute,
+ and each foreign key will produce two attributes (see the paragraph about <a href="./user-guide.html#foreign-keys">foreign keys</a> in the User Guide).</p>
+ <p>You can thus start with the minimal configuration, which only specifies the database connection parameters (don't forget
+ to specify the schema if you use one):</p>
+<div class="source"><pre><?xml version="1.0"?>
+<database user='<i>login</i>' password='<i>password</i>' url='<i>database_url</i>' schema='the_schema'>
+</database></pre></div>
+ <p>You can then check your installation with a very simple template that displays a few values taken from the database.</p>
+ <p>Next, please refer to the <a href="./user-guide.html">User Guide</a> and the <a href="./configuration">Configuration Reference</a>
+ to tune your model file.</p>
+ <p>The model file supports the XML XInclude mechanism, which lets you split a big model into many files.</p>
+</div>
+</div>
+ </body>
+
+</html>
Added: velocity/sandbox/velosurf/docs/logo.png
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/logo.png?rev=1298906&view=auto
==============================================================================
Binary file - no diff available.
Propchange: velocity/sandbox/velosurf/docs/logo.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: velocity/sandbox/velosurf/docs/overview.html
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/overview.html?rev=1298906&view=auto
==============================================================================
--- velocity/sandbox/velosurf/docs/overview.html (added)
+++ velocity/sandbox/velosurf/docs/overview.html Fri Mar 9 16:23:25 2012
@@ -0,0 +1,444 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
+<title>Velosurf - Overview</title>
+ <link rel="stylesheet" href="./velosurf.css" type="text/css">
+</head>
+
+<body>
+
+<div id="container">
+<div id="header">
+<div id="logo1"><img style="height: 60px;" alt="Velosurf logo" src="logo.png" border="0"></div>
+
+<div id="logo3"><img alt="Velosurf title" src="title.png" border="0"></div>
+
+<div id="logo2"><a href="http://jakarta.apache.org/velocity/"><img style="width: 80px;" src="powered-by-logo.gif" alt="Velocity" border="0"></a></div>
+
+</div>
+
+<div id="menu">
+<div class="menusection"><span class="menuheader">Velosurf</span>
+<ul>
+
+ <li><a href="./index.html">Home</a> </li>
+
+ <li><b>Overview</b>
+ </li>
+
+ <li><a href="./download.html">Download</a>
+ </li>
+
+ <li> <a href="./faq.html">FAQ</a> </li>
+
+ <li> <a href="http://velocity.apache.org/contact.html">Mailing lists</a> </li>
+
+</ul>
+
+</div>
+
+<div class="menusection">
+<span class="menuheader">Docs</span>
+<ul>
+
+ <li><a href="./installation.html">Installation</a></li>
+
+ <li><a href="./configuration.html">Configuration</a></li>
+
+ <li><a href="./user-guide.html">User Guide</a></li>
+
+ <li> <a href="./vtl-reference.html">VTL Reference</a> </li>
+
+ <li><a href="./api/index.html">Javadoc</a></li>
+
+ <li><a href="./architecture.html">Architecture</a></li>
+
+ <li><a href="./velosurf/docs/index.html">1.4.x Docs</a></li>
+
+ <li> <a href="./CHANGELOG">Change Log</a> </li>
+
+ <li> <a href="./LICENSE">License</a></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<div id="body">
+<a name="WhatisVelocity?"></a>
+<h1 align="left">Principles</h1>
+
+<p align="left">Using the Velocity variable that
+references the Velosurf tool in the Velocity context, template writers
+can access all (or a subset of) the tables of a database, that are
+called Velosurf <b>entities</b>. Entities
+properties are <b>attributes</b> (that can be table
+columns as well as customized queries). Entities methods that trigger
+database update/delete/insert queries are <b>actions</b>.
+Each realization of an entity is an <b>instance</b>.</p>
+
+<p align="left">Velosurf uses an XML configuration file
+that:</p>
+
+<ul>
+
+ <li>
+ <p style="margin-bottom: 0cm;" align="left">contains
+all necessary parameters to connect to the database. </p>
+
+ </li>
+
+ <li>
+ <p style="margin-bottom: 0cm;" align="left">contains
+the definition of all needed custom SQL entities, attributes and
+actions. </p>
+
+ </li>
+
+ <li>
+ <p align="left">defines the access rights to entities.
+ </p>
+
+ </li>
+
+</ul>
+
+All queries are done via a pool of prepared statements automatically
+handled by Velosurf.<br>
+
+<h1 align="left">Entities, Instances, Attributes and
+Actions</h1>
+
+<ul>
+
+ <li>
+ <p align="left"><b>Entities</b> are the
+objects that map database tables. By default, Velosurf defines an
+entity for each table. Entities are used to access Instances, either by
+the mean of #foreach loops or via one of the <i>fetch</i>
+methods.</p>
+
+ </li>
+
+ <li>
+ <p align="left"><b>Instances</b> map rows
+of a table (or of the result set of a customized query): they are a
+realization of their corresponding entity. Instances are used to access
+specific fields, attributes or actions.</p>
+
+ </li>
+
+ <li>
+ <p align="left"><b>Attributes</b> belong
+either to the database itself ('root' attributes) or to specific
+entities, in which case they can be accessed from the corresponding
+instances. Attributes have a result type which is one of 'scalar',
+'row', or 'rowset'. One can specify the resulting entity of row or
+row set attributes, to access nested properties on them. By default,
+Velosurf defines a scalar attribute for each table column.</p>
+
+ </li>
+
+ <li>
+ <p align="left"><b>Actions</b> are like
+attributes, except their SQL query is a modification query
+(insert/update/delete), or even a succession of such modification
+queries (a transaction that will rollback as a whole in case of
+failure). They return the number of affected rows. If present, the root
+action named 'startup' is executed at startup. </p>
+
+ </li>
+
+</ul>
+
+<h1 align="left"><a name="syntax"></a>What
+does the syntax look like?</h1>
+
+<p align="left"><b>Exampe #1: fetch a single value
+of the database and display it</b></p>
+
+<p align="left">Assuming that you've got the following
+table, called "message", in your database:</p>
+
+<table style="width: 145px; height: 61px;" border="1" cellpadding="2" cellspacing="2">
+
+ <tbody>
+
+ <tr>
+
+ <td align="center"><b>id</b></td>
+
+ <td align="center"><b>text</b></td>
+
+ </tr>
+
+ <tr>
+
+ <td align="center">1</td>
+
+ <td align="center">"Hello World!"</td>
+
+ </tr>
+
+ <tr>
+
+ <td>2</td>
+
+ <td>"How are you?"</td>
+
+ </tr>
+
+ </tbody>
+</table>
+
+<br>
+
+<p align="left">then you can write the following VTL
+expression:</p>
+
+<ul>
+
+ <p align="left"><code>$db.message.fetch(1).text</code>
+ </p>
+
+</ul>
+
+<p align="left">Or, to be more explicit:</p>
+
+<ul>
+
+ <p align="left"><code>#set( $hello =
+$db.message.fetch(1) )<br>
+
+$hello.text</code> </p>
+
+</ul>
+
+<p align="left">and this would produce:</p>
+
+<ul>
+
+ <p align="left"><code>Hello World!</code></p>
+
+</ul>
+
+<p align="left"><b>Example #2: fetch multiple rows
+of a single column and display them in sequential order</b></p>
+
+<p align="left">Still with the same table:</p>
+
+<ul>
+
+ <p align="left"><code>#foreach( $message in
+$db.message )<br>
+
+ $message.text<br>
+
+#end</code> </p>
+
+</ul>
+
+<p align="left">and this would produce:</p>
+
+<ul>
+
+ <p align="left"><code>Hello World!<br>
+
+How are you?</code></p>
+
+</ul>
+
+<p align="left"><b>Example #3: update or insert a
+value</b></p>
+
+<p align="left">Note: it's not advised to issue updates
+and inserts from inside templates, since it breaks the MVC paradigm.
+You should rather achieve this kind of stuff from your controller.</p>
+
+<ul>
+
+ <p align="left"><code>## update a value<br>
+
+#set( $message =
+$db.message.fetch(1) )<br>
+
+#set( $message.text = "Hello everybody!" )<br>
+
+#set( $success = $message.update() )<br>
+
+#if(!$success)<br>
+
+ An error occured: $db.error<br>
+
+#end<br>
+
+ <br>
+
+## insert a value<br>
+
+#set( $newMessage = { id:3; text:'Fine, thank you.'})<br>
+
+#set( $success = $db.message.insert($newMessage) )<br>
+
+#if(!$success)<br>
+
+ An error occured: $db.error<br>
+
+#end<br>
+
+ </code></p>
+
+</ul>
+
+<p>If you are using the velosurf.tool.HttpQueryTool tool to
+parse HTTP query parameters, you can pass it directly to an insert or
+an update method:</p>
+
+<ul>
+
+ <p><code>#set( $success = $db.message.insert($query) )<br>
+
+ </code><code>#if(!$success)<br>
+
+ An error occured: $db.error<br>
+
+#end<br>
+
+ </code></p>
+
+</ul>
+
+<h1 align="left">A simple example</h1>
+
+<p align="left">Suppose we've got two joined tables <code>user (id integer primary key, name varchar(50))</code>
+and <code>message(id integer primary key autoincrement, userid integer references user(id),txt varchar(255))</code>.
+</p><p>We want to list the messages per user, and to be able to add or delete messages. We'll rely on the Velosurf reverse engineering
+to define the <code>$db.user</code> and <code>$db.message</code> entities, as well as the <code>$message.user</code>
+and <code>$user.messages</code> attributes.</p>
+<p>First, the toolbox.xml (that references all Velocity tools) defines the
+needed tools:</p>
+<ul>
+ <li><code>db</code> will be the key to access the
+database</li>
+ <li><code>query</code> will be the key to access
+http
+parameters
+ </li>
+</ul>
+<p align="left"></p>
+<div class="source"><xmp><?xml version="1.0"?>
+<toolbox>
+ <!-- http query parameters -->
+ <tool>
+ <key>query</key>
+ <class>velosurf.web.HttpQueryTool</class>
+ <scope>query</scope>
+ </tool>
+ <!-- database -->
+ <tool>
+ <key>db</key>
+ <class>velosurf.web.VelosurfTool</class>
+ <scope>query</scope>
+ </tool>
+</toolbox></xmp></div>
+<p>Then, the velosurf.xml configuration file, which gives connection parameters. Nothing more to put here than
+connection parameters, since we use reverse engineering.</p>
+<div class="source"><xmp><?xml version="1.0" encoding="UTF-8"?>
+<database user="foo" password="bar" url="jdbc:mysql://127.0.0.1/messageboard" driver="org.gjt.mm.mysql.Driver" read-only="false" reverse="full">
+<!-- without reverse engineering, we would need the following definitions:
+ <entity name="user">
+ <rowset name="messages" result="message">select * from message where msg_user=<user_id/></rowset>
+ </entity>
+ <entity name="message">
+ <row name="user" result="user">select * from user where id=<userid/></row>
+ </entity>
+Note that when using reverse engineering, you can still list entities here if you want to customize them
+-->
+</database></xmp></div>
+<p>Now, the template itself:</p>
+<div class="source"><xmp><body>
+<h3>Very Simple Message Board</h3>
+
+#if ($query.action == "insert")
+ #set( $success = $db.message.insert($query) )
+#elseif ($query.action == "delete")
+ #set( $test = $db.message.fetch($query.id) )
+ #set( $success = $test.delete() )
+#end
+#if( !$success ) Error : $db.error #end
+
+<b>Messages for user:</b>
+<form>
+ <select name="userid">
+ #foreach($u in $db.user)
+ <option value="$u.id" #if($u.id == $query.userid)selected#end>$u.name</option>
+ #end
+ </select>
+ <input type="submit" value="Display">
+</form>
+
+#if($query.userid)
+ #set($user = $db.user.fetch($query.userid))
+ <ul>
+ #foreach ($message in $user.messages)
+ <li>$message.txt
+ <form>
+ <input type="hidden" name="id" value="$message.id">
+ <input type="hidden" name="action" value="delete">
+ <input type="submit" value="Delete">
+ </form>
+ </li>
+ #end
+ </ul>
+#end
+
+<b>New message:</b>
+<blockquote>
+<form>
+ <input type="hidden" name="action" value="insert">
+ For user: <select name="userid">
+ #foreach($u in $db.user)
+ <option value="$u.id" #if($u.id == $query.userid)selected#end>$u.name</option>
+ #end
+ </select><br>
+ Text: <input type="text" name="txt"><br>
+ <input type="submit" value="Insert">
+</form>
+</blockquote>
+</body>
+</html></xmp></div>
+<p>Of course, there is no data validation, no html escaping, no authentication (each user can see the messages of others),
+so we'd need some more work towards a real-life message board, but we already have something functional with few lines of code.</p>
+<p>The output would be something like this:</p>
+<div class="frame">
+<h3>Very Simple Message Board</h3>
+<b>Messages for user:</b>
+ <select name="userid">
+ <option value="1" selected>Bart</option>
+ <option value="2">Omer</option>
+ </select>
+ <input type="button" value="Display">
+ <ul>
+ <li>D'oh<input type="button" value="Delete"></li>
+ <li>Huuummmph<input type="button" value="Delete"></li>
+ </ul>
+
+<b>New message:</b>
+<blockquote>
+ For user: <select name="userid">
+ <option value="1">Bart</option>
+ <option value="2" selected>Omer</option>
+ </select>
+<br>
+ Text: <input type="text" name="txt"><br>
+ <input type="submit" value="Insert">
+</form>
+</blockquote>
+</div>
+</div>
+</div>
+
+</body>
+</html>
Added: velocity/sandbox/velosurf/docs/powered-by-logo.gif
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/powered-by-logo.gif?rev=1298906&view=auto
==============================================================================
Binary file - no diff available.
Propchange: velocity/sandbox/velosurf/docs/powered-by-logo.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: velocity/sandbox/velosurf/docs/title.png
URL: http://svn.apache.org/viewvc/velocity/sandbox/velosurf/docs/title.png?rev=1298906&view=auto
==============================================================================
Binary file - no diff available.
Propchange: velocity/sandbox/velosurf/docs/title.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream