Installation

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

Content:
 Building the Velosurf archive
 Configuring the toolbox
 Configuring Velosurf

Building the Velosurf archive

The last release is included in the /bin directory, but if you want to re-build the library, you need to have ant installed.

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

• jar: builds ./bin/velosurf-0.x.jar
• javadoc: builds the javadoc in ./docs/api
• tarball: builds the distribution tarball

Configuring the toolbox

The following instructions detail how to use Velosurf as a Velocity tool using the VelocityViewServlet and the toolbox.xml mechanism.

First, you need to set up the Velocity toolbox in your Webapp. This involves:

• copying needed archives from ./lib to /WEB-INF/lib
• inheriting the servlet(s) used to render templates from the class org.apache.velocity.tools.view.servlet.VelocityViewServlet (which you can also use directly)
• adding a reference to the toolbox in the context-parameters of the Webapp deployment descriptor (web.xml):

  <context-param>
    <param-name>org.apache.velocity.toolbox</param-name>
    <param-value>/WEB-INF/toolbox.xml</param-value>
  </context-param>

• adding a reference to the velosurf XML config file, if the default name (velosurf.xml) is not ok for you, at the same place:

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

Then, you can set up the Velosurf tools in /WEB-INF/toolbox.xml, like:

<?xml version="1.0"?>
<toolbox>

  <!-- http query parameters tool:
You can either use org.apache.velocity.tools.view.tools.ParameterParser
or velosurf.tool.HttpQueryTool.
If you are using the autofetch feature, the Velosurf version is mandatory.
    -->

  <tool>
    <key>query</key>
    <scope>request</scope>
    <class>org.apache.velocity.tools.view.tools.ParameterParser</class>
  </tool>

  <!-- database -->

  <tool>
    <key>db</key>
    <scope>request</scope>
    <class>velosurf.tools.VelosurfTool</class>
  </tool>

</toolbox>

Configuring Velosurf

Velosurf will search for a default configuration file named '/WEB-INF/velosurf.xml'. Its goal is to gather all SQL code.

If you wish to change its name, you can set the appropriate context-param in your Webapp, with 'velosurf.config' as key and the target file as value.

By default, the database will be reverse enginered and each table becomes an entity, each column an attribute. But this file lets you fully customize entities and attributes.

You can start with the minimal configuration, that only specify the database connection parameters:

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

You can then check your installation with a very simple template that checks that you can see your tables.