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
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
2.3 How do I use Velosurf with DVSL? Check the DVSL doc on how to create a toolbox. Then, include the line "
2.4 How do I use Velosurf with Texen? Put the line "
3. SQL Questions
3.1 What about primary and foreign keys? Primary keys are reverse enginered and used by Velosurf in all the
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.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!