Installation Instructions

Software Requirements

The server machine requirements :

  • Java Development Kit
  • Servlet Container
  • XML Parser
  • Running Database
  • Database JDBC driver or the database is going to be use, and capable of using, Java's JDBC:ODBC bridge driver

The client machine requires a browser with the following capabilities :

  • Enabled to accept cookies
  • Run javascript with close compliance with the European Computer Manufacturers Association ECMA-262 standard

'Quick' Installation Instructions

If you have a server with a database management system and a Servlet Container capable of running Jakarta Struts already configured the installation involves :

  • Copying the downloaded pgdbvu.war file into your webapps directory.
  • Make the database JDBC driver(s) available to the server container. This is outlined in the Struts documentation, the easiest way is to place the driver in the webapps/pgdbvu/WEB-INF/lib directory. This is not necessary if the database uses the JDBC:ODBC bridge which is part of the recommended Java development kit.
  • Configure at least one Data Source for the JDBC driver in the webapps/pgdbvu/WEB-INF/struts-config.xml file. Replace the examples in the <data-sources> section with the data appropriate to your driver and database.
  • You can configure as many Data Sources as you wish to make available to the users. If you are running more than one type of database that requires different drivers then these need to be made available as outlined above.

'Detailed' Installation Instructions

Server Machine

Jakarta Struts

pgdbvu uses Struts a Jakarta Project to provide a framework for building web applications. The installation requirements for this application are therefore the same as that for Struts. The full Struts installation guide can be found at http://jakarta.apache.org/struts/installation.html. In brief the requirements for Struts are:

  • Java Development Kit - Java2 (version 1.2 or later) Java Development Kit implementation for your operating system platform (if unsure try http://java.sun.com/j2se). This application has been developed and tested using java j2sdk1.4.1_01 from Sun.
  • Servlet Container - A servlet container that is compatible with the Servlet API Specification, version 2.2 or later, and the Java Server Pages (JSP) Specification, version 1.1 or later (if unsure try Apache's Tomcat (version 3.1 or later required, version 3.2 or later recommended). This application has been developed and tested using Tomcat versions 4.0.6, 4.0.10, 4.1.12, 4.1.16 and 4.1.18 from Jakarta.
  • XML Parser - An XML parser that is compatible with the Java API for XML Parsing (JAXP) specification, 1.1 or later (if unsure try the JAXP reference implementation). As previously stated this application was written with java j2sdk1.4.1_01 which includes an XML parser.

The application contains a Struts binary distribution in the Web Application Archive (WAR) file so it is not necessary to obtain a Struts distribution. This project has been developed and tested on Struts versions 1.0.2, 1.1-b2 and a number of the nightly builds.

For information and trouble shooting a Struts installation the best starting point is the Struts website http://jakarta.apache.org/struts/ which provides detailed information on all aspects of Struts including many other resources and references.

Application Installation

After successfully installing a servlet container which is capable of running Struts. Stop the servlet and copy the downloaded pgdbvu.war (WAR) file into the web applications servlet container directory. For simplicity this directory, from now on, will be referred to as webapps. Start the server again this will create a pgdbvu directory from the WAR file. Therefore the installation procedure is :

  • Stop the server.
  • Copy the pgdbvu.war file into your webapps directory.
  • Start the server, to produce the pgdbvu directory.

The pgdbvu directory will now contain the following directory structure and files (bold indicates a directory). The files marked with a * are from the Struts binary distribution, the ** is the struts-config.xml file replacing the one provided in the Struts binary distribution with an application specific version. This WAR provides the source application code as well as the compiled files :


META-INF
  MANIFEST.MF
WEB-INF
  classes
      pgdbvu
        ConnectAction.java
        ConnectAction.class
        ConnectFormBean.java
        ConnectFormBean.class
        DBConnection.java
        DBConnection.class
        DBInfo.java
        DBInfo.class
        DBMetaData.java
        DBMetaData.class
        DBMetaDataAction.java
        DBMetaDataAction.class
        DBMetaDataFormBean.java
        DBMetaDataFormBean.class
        DBTree.java
        DBTree.class
        QueryAction.java
        QueryAction.class
        QueryFormBean.java
        QueryFormBean.class
        TreeAction.java
        TreeAction.class
        TreeFormBean.java
        TreeFormBean.class
        ViewTableAction.java
        ViewTableAction.class
        ViewTableFormBean.java
        ViewTableFormBean.class
      resources
        application.properties
    struts-config.xml
  lib
    commons-beanutils.jar*
    commons-collections.jar*
    commons-dbcp.jar*
    commons-digester.jar*
    commons-fileupload.jar*
    commons-lang.jar*
    commons-logging.jar*
    commons-pool.jar*
    commons-resources.jar*
    commons-services.jar*
    commons-validator.jar*
    jakarta-oro.jar*
    struts.jar*
  struts-bean.tld*
  struts-config.xml**
  struts-html.tld*
  struts-logic.tld*
  struts-nested.tld*
  struts-template.tld*
  struts-tiles.tld*
  tiles-defs.xml*
  validation.xml*
  validator-rules.xml*
  validator.xml*
  web.xml*
apache-license.txt
index.jsp
install.html
install.txt
license.txt
pages
    about.jsp
    app.css
    banner.jsp
    blank.jsp
    buttons.jsp
    connect.jsp
    dbmetadata.jsp
    error.jsp
    footer.jsp
    header.jsp
    help.jsp
    images
     arrowdown.gif
      arrowup.gif
      clear.gif
      clear8x8.gif
      connect.gif
      cross.gif
      db.gif
      disconnect.gif
      document.gif
      emptybox.gif
      field.gif
      help.gif
      index.gif
      info.gif
      key.gif
      pgdbvu.gif
      print.gif
      profile.gif
      query.gif
      refresh.gif
      table.gif
      tables.gif
      tick.gif
      tree_empty.gif
      tree_minus.gif
      tree_plus.gif
      view.gif
    index.jsp
    license.jsp
    query.jsp
    tree.css
    tree.js
    tree.jsp
    treemessage.jsp
    viewTable.jsp
pgdbvu.css
revision.txt

Database Configuration

Stop the server whilst configuring the datasource.

It is assumed that you have at least one database which you wish to enable access to with this web application (pgdbvu). It is also assumed that the database is in a state where connections may be made by your web server (servlet container). This may require specific configuration modifications to the database setup usually concerning authorization and security issues. The details will be found in your database documentation.

If you are on a Windows system and connecting to a database with the JDBC:ODBC bridge and the database is a file which does not require part of the database system to be running for a third party application to connect to it. If an odbc driver is available it is only necessary to use the odbc configuration utility.

If you intend using a JDBC driver other than the JDBC:ODBC bridge which is included in the standard Java 2 distribution it will be necessary to make the driver available for use with your java servlet container. How to do this will be outlined in the documentation for your specific container servlet but the easy way is to place the JDBC driver JAR file in the webapps/pgdbvu/WEB-INF/lib directory.

The struts-config.xml file needs to be modified to include the Data Source configuration which will enable access to the database through the JDBC driver. The fact that a database is only available if it has been configured in this file provides a certain level of security. Below are a few example configurations, each individual Data Source configuration must lie between the <data-sources> and </data-sources> tags. Each <data-source> must be set up as a "org.apache.commons.dbcp.BasicDataSource" using the type attribute. Each <data-source> tag must have a key attribute specified, since this is used in the connection form to create an option selector to make a connection to the configured Data Source. The username and password properties may be left out. These are used if an incorrect username and/or password are specified in the application connection form. It can be useful to set these at a low authorization level thus providing a 'guest' access to the database rather than refusing access if the user has not got a username and password.

A sample Data Source Configuration :

  <data-sources>

    <!-- configuration for commons BasicDataSource (Postgresql) -->
    <data-source key="postgresqltestds" type="org.apache.commons.dbcp.BasicDataSource">
      <set-property
        property="driverClassName"
        value="org.postgresql.Driver" />
      <set-property
        property="url"
        value="jdbc:postgresql://localhost/postgresqltest" />
      <set-property
        property="maxActive"
        value="10" />
      <set-property
        property="maxWait"
        value="5000" />
      <set-property
        property="defaultAutoCommit"
        value="false" />
      <set-property
        property="defaultReadOnly"
        value="false" />
      <set-property
        property="username"
        value="postgresqltestusername"/>
      <set-property
        property="password"
        value="postgresqltestpassword"/>
    </data-source>

    <!-- configuration for commons BasicDataSource (MySQL) -->
    <data-source key="mysqltestds" type="org.apache.commons.dbcp.BasicDataSource">
      <set-property
        property="driverClassName"
        value="org.gjt.mm.mysql.Driver" />
      <set-property
        property="url"
        value="jdbc:mysql://localhost/mysqltest" />
      <set-property
        property="maxActive"
        value="10" />
      <set-property
        property="maxWait"
        value="5000" />
      <set-property
        property="defaultAutoCommit"
        value="false" />
      <set-property
        property="defaultReadOnly"
          value="false" />
      <set-property
        property="username"
        value="mysqltestusername"/>
      <set-property
        property="password"
        value="mysqltestpassword"/>
    </data-source>

    <!-- configuration for commons BasicDataSource (Odbc) -->
    <data-source key="testodbcds" type="org.apache.commons.dbcp.BasicDataSource">
      <set-property
        property="driverClassName"
        value="sun.jdbc.odbc.JdbcOdbcDriver" />
      <set-property
        property="url"
        value="jdbc:odbc:testodbc" />
      <set-property
        property="maxActive"
        value="10" />
      <set-property
        property="maxWait"
        value="5000" />
      <set-property
        property="defaultAutoCommit"
        value="false" />
      <set-property
        property="defaultReadOnly"
        value="false" />
      <set-property
        property="username"
        value="testodbcusername"/>
      <set-property
        property="password"
        value="testodbcpassword"/>
    </data-source>

  </data-sources>

Further detailed information for configuring a "org.apache.commons.dbcp.BasicDataSource" can be found at the Struts website http://jakarta.apache.org/struts/.

I have tested this application with Postgresql 7.3 and pg73jdbc3.jar JDBC driver, MySQL 3.23 with mm.mysql-2.0.14-bin.jar JDBC driver on a Linux system and the JDBC:ODBC bridge on various flavours of Windows and different database file types among which are MS Access, FoxPro, Paradox and dBase files. Interbase version 5.5 which requires its "guardian" running has also been tested and successfully connected to using the JDBC:ODBC bridge. The largest table I was able to test pgdbvu with has nearly 27000 records, it succeessfully retrieved all the records without complaint (apart from the expected delay). This just about exhausts all the databases and JDBC drivers I currently have. As previously stated the application should work with any JDBC compliant database and driver combination.

The application is now installed and configured and should be available when your container servlet is started.

Client Machine

The client machine only requires a web browser which must be enabled to accept cookies and run javascript with close compliance with the European Computer Manufacturers Association ECMA-262 standard. I have tested this application with a number of browsers which use the Mozilla core (e.g. Mozilla, Netscape 6, 7 and Galeon) and Microsoft Internet Explorer 6 (but IE5 or above should be fine).

Starting a web browser and specifying the pgdbvu URL should enable you to use the application.

Once the application is being viewed in the browser a help facility is available on how to use it.

General Note

The above may all sound quite complicated but to anyone familiar with web applications should be quite straight forward. In brief the installation involves placing the downloaded WAR file into the servers webapps directory. Starting the server, to create the application directory. Make the required JDBC drivers available to the container servlet. Finally after stopping the server modify the struts-config.xml file to make the Data Sources available to the application.

Known problems

Server Machine

I have developed this application on a Linux system in some cases when used on a Windows machine the difference between the way Linux and Windows handles carriage return and line feed can cause problems. This only affects the JSP pages and may result in the servlet container not being able to compile and make these pages available thus throwing a servlet error. In these cases the simple fix is to open the JSP files in an editor which can handle Linux/Unix end of line characters (e.g. Wordpad NOT Notepad) and resave them.

Configuration of a datasource in the struts-config.xml file which has not got the JDBC driver available can result in the server throwing spurious errors. The errors may not appear to be related in anyway to the datasource. If pages are not being served up correctly it is worth checking your datasource configuration and associated JDBC driver.

Client Machine

Since the client machine only runs a browser they are all browser specific problems.

  • All Netscape 4 and earlier versions will not work, due to the fact that they are not compliant with the specified version of javascript.
  • Konqueror version 3.0.1 is unable to highlight the tree, not sure about later versions.
  • Internet Explorer does not clear its query string when successive tree views are requested. The query string gets longer and longer and when it reaches a certain limit (not checked, not interested!) will not add any more characters. This failing has been facilitated for to an extent in the application by only extracting the required section of the successively concatenated query strings but does not facilitate for reaching the limit. This problem can be circumvented by requesting a different page (e.g. clearing the content frame) which clears the view query string.

General

This is a new application and where appropriate I have stated which databases, JDBC drivers, servlet containers, browsers, Java and operating system specific types and versions it has been tested with. This list is fairly short so it would be interesting to hear feedback on successes or failures with different combinations. The source is included so feel free to make alterations where necessary.

All software reviews (that's a joke) have been carried out by myself and may as a result not have been particularly objective or critical. All testing likewise has been down to me so may not have been as thorough as by a third party. Hopefully these facts do not show up when you are running the software.

Jakarta Struts License

In providing a binary Struts distribution in the WAR download file I should make it clear that this software is distributed under a different license to this application. The Jakarta Struts license is covered by the Apache license and can be found on their website at www.apache.org/LICENSE. A copy of this license is included in the WAR file since this is a requirement for any redistribution of Apache software.