The tutorial needs to be included in the servlet engine's configuration file. For Tomcat, a Context element has to be added to the conf/server.xml file.

Next, the tables must be defined in the RDBMS and a user account created. The tutorial has three subdirectories under examples/tutorial/WEB-INF called db_hsql, db_pgsql, and db_mysql that provide scripts for the HSQL, PostgreSQL, and MySQL databases. The HSQL database is provided as a shortcut for executing the tutorial. By specifying that database (already specified in the tutorial dbforms-config.xml file), the tutorial application can be run without using any other database system.

To use the PostgreSQL or MySQL RDBMSs, create a tutorial database and a tutorial user using database tools. Then, execute the appropriate tutorial.script file to define tables and populate some initial data for the application. Changes will probably be required to use another RDBMS because the orders and complaints tables use generated keys which are non-standard.

Once the database tables are created and populated, the dbconnection element needs to be updated to use the selected RDBMS. Using the DevGui program is a good way to configure and debug this portion. Once the database is reachable via DevGui, let DevGui write a configuration file. The database connection element can then be extracted and copied to the tutorial configration file. Otherwise, changes to the dbforms-config.xml can be made by hand.

The final step is to copy the DbForms tag library and dependencies to WEB-INF directory. The file bin/dbforms.tld must be copied to the WEB-INF directory itself. The file bin/dbforms X.Y .jar (where X.Y is the release number) must be copied to the WEB-INF/lib directory. The contents of the dependend directory must also be copied to the WEB-INF/lib directory.

The application should now be ready to run. As a check, review the typical directory structure in Section 4.3.2, “Typical deployment structure of applications using DbForms” and compare it to the structure of the tutorial as you've modified it.

Errors in the dbforms-config.xml file often cause errors in the execution of the DbForms web application.

Whenever a change is made to the configuration file, it is wise to check the servlet engine log files for any errors listed there. In particular, if an error occurs in parsing the configuration file, it is often the case that the database connection is not processed since it occurs near the end of the configuration file. This means that when the application is executed, a database error will be reported (usually mentioning name=null) when the real error occurred earlier in the configuration file.

Once there are no parse errors in the configuration file, try the DbForms application. The most common type of problem at this point is a non-working database connection. The error reported, however, will be different than those described in the previous paragraph.

If the database connection is not working, check the servlet engine log. For Tomcat, this will be the catalina.out file. In the case of Tomcat, there will usually be two tracebacks in the log. The first traceback is immediately preceded by another error message that indicates the source of the problem such as an authentication error or a class-not-found error.

When the configuration file is error free and the database connection is working, the application should come together very quickly.