Frequently Asked Questions
Table of Content
- General Questions
- Installation, Configuration and Integration
- How do I use Velosurf within my Webapp?
- How do I use Velosurf within my Java application?
- How do I use Velosurf with Ant?
- How do I use Velosurf with DVSL?
- How do I use Velosurf with Texen?
- SQL Questions
- Velosurf and the MVC Design Pattern
- What does MVC stand for?
- Is Velosurf MVC-compliant?
- How to use different logins with different accesses to the database?
- Troubleshooting
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 engineering 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 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).
2. Installation, Configuration and Integration
2.1 How do I use Velosurf within my Webapp?
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 velocity-tools 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.
2.2 How do I use Velosurf within my Java application?
First, you must ensure that Velosurf will find
its configuration file, as explained here. Then you just have
to put an instance of velosurf.Velosurf in the Velocity context.
2.3 How do I use Velosurf with Ant?
You will have to use VPP. Please have a look at the example provided
in example/ant-vpp for how to proceed.
2.4 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 (see 2.2).
2.5 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 (see 2.2).
3. SQL Questions
3.1 What about primary and foreign keys?
Primary keys are reverse engineered and used by Velosurf
in all the fetch 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 this section for more details.
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).
4.3 How to use different logins with different accesses to the database?
Just have two different configuration files. You can factorize the model using the <xi:include> syntax.
5. Troubleshooting
5.1 It doesn"t work! What can I do?
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. What is the problem?
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.