The server machine requirements :
The client machine requires a browser with the following capabilities :
'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 :
'Detailed' Installation Instructions
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:
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.
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 :
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 :
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 :
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.
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.
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.
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.
Since the client machine only runs a browser they are all browser specific problems.
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.