A skeleton of this tutorial is located in the
directory of the distribution. The example, however, is not
ready to run. This section gives the steps needed to make the
tutorial functional. Begin by checking that all of the
prerequisites listed in
Section 4.1, “Prerequisites”
have been accomplished.
The tutorial needs to be included in the servlet engine's
configuration file. For Tomcat, a
Context element has to
be added to the
Next, the tables must be defined in the RDBMS and a user account
created. The tutorial has three subdirectories under
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
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
file to define tables and populate some initial data for the
application. Changes will probably be required to use another RDBMS
tables use generated keys which are non-standard.
Once the database tables are created and populated, the
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
can be made by hand.
The final step is to copy the DbForms tag library and
directory. The file
must be copied to the
directory itself. The file
(where X.Y is the release number) must be copied to the
directory. The contents of the
directory must also be copied to the
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
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.