Velosurf FAQ

1. General Questions

1.1 What is Velosurf? Velosurf is a light and flexible Java library meant to expose a relational database to Jakarta Velocity templates. Velosurf does an automatic reverse enginering of a database source and provides a default mapping that can then be extended and customized in many ways.

1.2 How do I use it? Velosurf provides the Velocity context with a $db 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.

1.3 How does it work? 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 enginering 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).

2. Installation and configuration

2.1 How do I use Velosurf within my Webapp? The easiest way is to use the VelocityViewServlet class (or a subclass), provided with the velocity-tools subproject: it provides a generic plugin mechanism enabling external tools to be automatically plugged into Velocity contexts, with scope considerations. Refer to the Installation page for more.

2.2 How do I use Velosurf within my application? First, you must ensure that Velosurf will find its config file, as explained here. Then you just have to put an instance of velosurf.standalone.Velosurf in the Velocity context.

2.3 How do I use Velosurf with DVSL? Check the DVSL doc on how to create a toolbox. Then, include the line "toolbox.tool.db=velosurf.standalone.Velosurf" in your toolbox.props file, and have Velosurf find its velosurf.xml configuration file, as explained here.

2.4 How do I use Velosurf with Texen? Put the line "context.objects.db=velosurf.standalone.Velosurf" in your texen.properties file, and have Velosurf find the velosurf.xml configuration file as explained here.

3. SQL Questions

3.1 What about primary and foreign keys? Primary keys are reverse enginered and used by Velosurf in all the fetch methods. For now, foreign keys are not reverse enginered but they can easily be specified in the configuration file, so that they appear as properties. You can then traverse foreign keys back and forth using the dot operator.

4. Velosurf and the MVC Design Pattern

4.1 What does MVC stand for? 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).

4.2 Is Velosurf MVC-compliant? 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).

5. Troubleshooting

5.1 It doesn't work! 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.

5.2 Velosurf connects to the database, but hangs right after, with no message. Have you provided a schema name ? Under Oracle for instance, there are so many system tables (several thousands) that the reverse enginering can be very long. You can also choose the "manual" reverse enginering option so that only the entities listed in velosurf.xml are processed.

Got another question not listed here? Ask the mailing list!