Installation

This page details the setup of Velosurf in a Webapp powered by Velocity Tools 1.4 or Velocity Tools 2.0. For other environments, you should refer to the FAQ or the mailing list.

You should be familiar with Velocity and the concept of Webapp to easily understand the following.

Building the Velosurf archive

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 ant installed.

Then, the ./build/build.xml file contains the following ant targets:

jar: builds ./velosurf-x.y.jar
download: downloads dependency jars in the ./lib directory
javadoc: builds the javadocs in ./docs/api
tarball: builds the distribution tarball velosurf-x.y.tgz
test: runs all the test cases.
clean: cleans all temporary files.
clean-all: cleans all temporary files and deletes all dependency jars.

Configuring the toolbox

First, you need to set up the Velocity toolbox in your Webapp. Please refer to VelovityView Tools 1.4 installation or to VelocityView 2.0+ installation.

Then, you have to set up the Velosurf tools by means of the /WEB-INF/toolbox.xml (for 1.4):

<?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>

Or /WEB-INF/tools.xml (for 2.0+):

<?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>

Notes:

by default, Velosurf searches for its model in /WEB-INF/model.xml or /WEB-INF/model.xml
you can use as many database tools as you wish (you may then use custom model filenames)
the velosurf.web.VelosurfTool 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.

Alternatively, the name of the configuration file can also be specified in the velosurf.config 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 /WEB-INF/web.xml:

<context-param> <param-name>velosurf.config</param-name> <param-value>/WEB-INF/db.xml</param-value> </context-param>

Configuring the Velosurf model

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 foreign keys in the User Guide).

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):

<?xml version="1.0"?>
<database user='login' password='password' url='database_url' schema='the_schema'>
</database>

You can then check your installation with a very simple template that displays a few values taken from the database.

Next, please refer to the User Guide and the Configuration Reference to tune your model file.

The model file supports the XML XInclude mechanism, which lets you split a big model into many files.