4.3. Building your own DbForms-capable applications

Use the checklist below as a guide for setting up a DbForms application.

  1. Copy the file bin/dbforms.tld from the DbForms distribution into the WEB-INF directory of your web application.

    Note. The file dbforms.tld was named taglib.tld in some prior versions. The name taglib.tld was changed because it was too generic and the risk of naming conflicts too great.

  2. Copy the file bin/dbformsX.Y.jar (where X.Y is the release number) from the DbForms distribution into the WEB-INF/lib directory of your web application.
  3. Copy the jars in the dependend directory of the DbForms distribution into the WEB-INF/lib directory of your web application.
  4. Create or modify the J2EE deployment descriptor WEB-INF/web.xml file to include the following items. See Section 4.3.1, “Edit deployment descriptor web.xml for more details.
    • Three servlet elements to define the control, config, and file servlets and their URL mappings. Other servlets may also be needed for additional capabilities such as JasperReports, Excel output, and CSV output.
    • A tag library declaration for the DbForms tag library.
    • Security measures for your application.
  5. Create a file WEB-INF/dbforms-config.xml that defines the tables, the fields, and the database connection to use. See Chapter 8, Configuration Files for details of the contents of this file. This can be generated AUTOMATICALLY (along with JSP pages) by using the DevGui application. See Chapter 5, DevGui for more information.

    It is also possible to use more than one configuration file. Simply list them with commas between them in the dbformsConfig init param of the ConfigServlet in web.xml as shown in this fragment from the dbforms-config.xml file.


  6. Optionally, create a WEB-INF/dbforms-errors.xml file that defines error messages. See the xmlErrors tag in the separate DbForms Custom Tag Library document in the docs/taglib directory for more information.
  7. In each JSP page that will use the DbForms custom tags, add a line at the top of the page like this:
       <%@ taglib uri="/WEB-INF/dbforms.tld" prefix="db" %>
    The prefix "db" followed by a colon is placed in front of each tag from the DbForms tag library. The above declaration gives the association between the tag library and the prefix. If you wish, you can use a prefix other that "db". This document, however, assumes a prefix of "db".
  8. Verify the structure of your deployment. See Section 4.3.2, “Typical deployment structure of applications using DbForms” for an example of a complete directory and file structure.
  9. Check that the database configuration defined in dbforms-config.xml is really working. Whether this is an easy task or not, depends heavily on the database server you are using. One way to do this is to use the database tab in DevGui (Section 5.4.2, “Database Tab”) to set up a simple, non-JNDI and non-connection pool connection. Common reasons for database-related problems are:
    • JDBC drivers not in classpath (of servlet container).
    • Connection pool classess not in classpath.
    • Driver/Connection-pool resources (property-files) not in classpath.
    • Misspelled connection URLs or JNDI keys.
    • Database authentication problems (network versus direct connect, user id, passwords).

4.3.1. Edit deployment descriptor web.xml Changes in web.xml to enable DbForms

The listing shown below is a complete deployment descriptor for a DbForms application. If the web application has additional servlets in addition to the servlets that comprise DbForms, they would be added to the descriptor in the normal manner.

The order of elements in web.xml is important so be sure to follow the DTD/Schema. For convenience, the top level of the root element web-app is shown below.

      web-app (icon?, display-name?, description?, distributable?,
      context-param*, filter*, filter-mapping*, listener*, 
      servlet*, servlet-mapping*, session-config?, mime-mapping*, 
      welcome-file-list?, error-page*, taglib*, 
      resource-env-ref*, resource-ref*, security-constraint*,
      login-config?, security-role*, env-entry*, ejb-ref*,  

Add the following servlet, servlet-mapping, taglib, and context-param (optional) elements to the web-app element in the /WEB-INF/web.xml file.

The sample listing below has portions keyed to remarks that follow.

  <?xml version="1.0" encoding="ISO-8859-1"?>

  <!DOCTYPE web-app
      PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"


    <!--============= DBFORMS STYLING TEMPLATES =============-->
      <param-name>templateBase</param-name> 1

    <!--=========== DbForms Configuration Servlet ===========--> 

        <param-name>log4j.configuration</param-name> 2


        <param-name>resourceBundle</param-name> 3

        <param-name>validation</param-name> 4

      <!--More than one validation file is possible-->


    <!--=========== DbForms Controller Servlet ==============-->     

        <param-name>maxUploadSize</param-name> 5

    <!--=========== DbForms FileServlet =====================--> 

    <!--==== Controller Servlet and FileServlet Mappings========-->


     <!--=========== Session config =====================-->


     <!--=========== Welcome File List =====================-->


     <!--=========== DbForms Tag Library Descriptor ==========--> 


     <!--=========== Application Security Controls ==========--> 




This is optional. See Section, “Template base directory ” for more information.


The initialization parameter log4j.configuration should point to a valid log4j property file. If this parameter is not defined, the log4j standard configuration will be used for logging.

Now that log4j handles all console output, you would think that by setting log4j to display fatal errors only, your console would be virtually empty. Well, no! The current version of DbForms uses the struts digester class to parse xml files at startup. This class sends info to System.out. The initialization parameter digesterDebugLevel setting can be used to specify (to the digester) the amount of detail to display. Values can range from 0 (no debug) to 10 (Show all).

Sample log4j.properties file:

   #begin log4j.props
   #IMPORTANT -  Watch for trailing whitespaces after each statement!!!

   #log4j.rootCategory=debug, stdout, logFile
   #log4j.rootCategory=warn, stdout
   log4j.rootCategory=error, stdout

   #out to console 

   # Pattern to output the caller's file name and line number. 
   log4j.appender.stdout.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

   #out to file 



DbForms v1.1 supports internationalization (i18n). Labels, messages, etc. can be stored in "resource bundle" files and retrieved using appropriate DbForm tags. The optional initialization parameter resourceBundle setting is used to specify the resource bundle root name. Refer to Section 16.2, “Defining Resource Bundles ” for more detail.


Enhanced validation features are available because the Apache Commons-Validator framework has been integrated into DbForms. This framework requires the use of two distinct xml descriptor files. The optional initialization parameters validator-rules and validation are used to specify these files. Refer to Section 17.1, “Commons-Validator framework ” for more discussion.


The initialization parameter maxUploadSize tells DbForms how big of a file upload it should accept. If no value is set, a default value will be used. Setting any kind of upload size is important to protect the system against DoS (Denial of Service) attacks. Deploying a security aware application

DbForms inherits all of the security controls present in the servlet container, either an application server or a dedicated servlet engine such as Tomcat. Therefore, please refer to documentation for the Application Server or Servlet Engine being used for information on this topic. The Java Servlet specification also contains information about web application security.

A typical security-aware web application deployment descriptor has elements inside its web-app element as shown below.

  <!-- ==================================================== -->
  <!-- =           APPLICATION SECURITY                   = -->
  <!-- ==================================================== -->

  <!-- =================== authentication ================= -->
    We protect everything in directory /protected
    however, be sure NOT to protect login.jsp or logout.jsp since,
    in most containers, this would lead to endless recursion
    which ends with a crash of the Java Virtual Machine ("StackOverFlow")



  <!--=================== login config ====================-->
    <realm-name>Form-Based Authentication Area</realm-name>


    <realm-name>Example Basic Authentication Area</realm-name>

  <!--=================== roles ===========================-->
    <description>Have read only access</description>

    <description>Registered users can do stuff, others not.</description>

    <description>Registered users can do less then users_a</description>


User authentication and mapping of users to roles are both performed by the servlet container. For Tomcat, this is controlled via the Realm element in the conf/server.xml file.

DbForms provide some additional security controls beyond the controls inherited through the container. See Chapter 9, Security for fine-grained definition of rights for data access and manipulation.

4.3.2. Typical deployment structure of applications using DbForms

Finally, here a short list of files to check when deploying a web application using DbForms:

Example 4.1. Structure of a typical DbForm application

Bold items are required.







The above list of required JAR files is dependent on the version of DbForms being used and also dependent on features of DbForms used in the application. The list is current as of version 2.5 but it is prudent to check the contents of directory dependend in the binary distribution since that directory defines the official set of dependencies.

The JDBC driver may, in some cases such as for simple connections, be placed in the WEB-INF/lib directory.

For Tomcat, the directory common/lib may also be used to place the DbForms JAR file and other dependencies in a single location that can be shared among multiple DbForms applications.

Other dependencies, such as JDBC drivers may be placed in Tomcat directory server/lib where they may be used by Tomcat to be shared among all web applications in the container.

In some cases, when there is a verson conflict between a DbForms dependency and the same library needed by the servlet container, a JAR file must be placed in the server/lib directory (or its equivalent in a container other than Tomcat) instead of the application's WEB-INF/lib directory.