Source code contributed to Expresso should follow certain guidelines. Contributors should follow the Sun Java Coding Conventions, except fot the following exceptions and clarifications:

A unified diff patch is the format that is used by Linux Kernel developers. This is a special type that preserves the differences between source files. On UNIX and Linux a context diff file is created with the diff command.

		
% diff -u  acme.java.org  acme.java > acme.java.diff.peter

Here a sensible developer backed up the original source and then made some modifications to a copy file. He, then, created a patch, a unified diff file. He sents the patch files to the lead developer who if she is also running a UNIX system can applied the patch. The lead developer will apply the patch like this:

% patch -p0 <  acme.java.diff.peter

Often a contributor has made a lot of changes across many files. On UNIX system a shell script can help reduce the work of creating patches. Here is a shell script that helps to generate unified diff patch. This scripts searches for files that suffixed by a particular extension, say `.orig'. The script creates patches, unified diffs, for each of these files automatically.

#!/bin/sh
# Program ``generate-patch'' Mon Sep 30 02:08:40 BST 2002

SysWarn ()
{
    echo "$myname: *WARNING* : $*" 1>&2
}

SysError ()
{
    echo "$myname: *ERROR* : $*" 1>&2
    exit 1
}

myname=`basename $0`
if [ -z $1 -o -z $2 ]; then
    cat <<-XEOF
    USAGE: $myname <DIRECTORY>  <DIFF-EXTENSION>

    Generates a software patch for any development application. 
    This program prints the diff to the standard output.
    e.g.

    % $myname   com/xenonsoft   .orig
XEOF
fi

directory=$1
extension=$2

if [ ! -d $directory ]; then
    SysError "no such directory: \`$directory'"
fi
if [ ! -r $directory ]; then
    SysError "cannot read directory: \`$directory'"
fi

find $directory \( -name "*$extension" -o -name "*.$extension" \) -type f -print |
while read file1 
do
    #  e.g  file1=acme.java.orig  =>  file2=acme.java  
    file2=`echo $file1 | sed 's!'$extension'$!!'`
    if [ ! -f $file2 ];then
	file2=`echo $file1 | sed 's!'\.$extension'$!!'`
    fi
    if [ ! -f $file2 ]; then
	SysWarn "cannot find missing patch file:\`$file2\'"
    else
	# Create unified diff patch
	diff -u $file1 $file2
    fi
done
# End-of-script

The script is typically used like this. I am assuming UNIX again.

% cd /home/blairt/proj/expresso

% generate-patch  \ 
	expresso-web/WEB-INF/src/com/jcorporate/core/dbobj   \
	.orig >  dbobj.diff.peterp-20020930

If you have a working CVS repository on your system then you can edit the diff line in the script file, so that you get difference up-to-date and accurate from CVS. Simply replace the the diff with the following

cvs diff -u $file2

The information in the section is distilled at Jakarta Apache Bug Submission web page

Due to natural testing habits, Expresso works best with the databases the core development team works with the most. These tend to be:

Other databases that are frequently used by community members but may not have up to date documentation or might have some testing issues are:

So what do you do if Expresso doesn't directly support your native database? Not a problem! The following section will help guide you through the process of how to port Expresso to your database. We will include sections on how to get a quick "Up And Running" and then later show you how to test the system so that you know that your configuration works for all Expresso-supported data types.

Before we proceed, let us encourage you that porting to a database is seldom a really painful process. Perhaps a field will need to be renamed, or perhaps the CREATE TABLE statement will have to be slightly modified, but in most cases, you won't have to modify Expresso's code at all.

Quick Start

The database porting process can, in a short diagram, be summed up like this:

Creating your initial database setup

You will need to create a skeletal jdbc entry in the database to get started. To find the entries you want, take a look at the database JDBC documentation. First off, a sample of a skeletal configuration:

	<context name="hypersonic" active="true">
		<description>Hypersonic Database</description>
		<jdbc 
			driver="org.hsqldb.jdbcDriver" 
			url="jdbc:hsqldb:%web-app%WEB-INF/db/default/default"
			connectFormat="3" 
			login="sa" 
			password="" 
			cache="y" 
			createTableIndicies="true" 
			limitationPosition="" 
			escapeHandler="com.jcorporate.expresso.core.db.DoubleQuoteEscapeHandler" 
			skipText="true"/>
		<!-- Type mappings eventually go here -->
		<type-mapping>
			<java-type>LONGVARCHAR</java-type>
			<db-type>LONGVARCHAR</db-type>
		</type-mapping>
		<images>%context%/%expresso-dir%/images</images>
		<startJobHandler>n</startJobHandler>
		<showStackTrace>y</showStackTrace>
		<mailDebug>n</mailDebug>
	</context>

Most of the items can be left as is, but the key would be the entries for the <jdbc> tag. Here is where you can get that information from your documentation.

Table A.1. JDBC Attributes

Attribute	What To Set It To
driver	Look at your driver docs. The value in Class.forName("database driver class"); will be what you want to set this value to.
url	Look for the URL the database driver is connecting to. Put that value here.
connectFormat	Most databases will work well with "1" Try other varieties if you have connection issues.
login	Depends on your database. The connection account Expresso should use for the database
password	Depends on your database. The connection password Expresso should use for the database.
cache	Usually set to "true"
createTableIndicies	Set to "true" unless your database has weird index creation routines and DBCreate fails on index creation. In this case you'll need to create database indicies manually.
limitationPosition	Leave Blank
escapeHandler	In most cases set to: com.jcorporate.expresso.core.db.DoubleQuoteEscapeHandler. This is for filtering the SQL strings against sql injection attacks so characters like "'" will work in a database query properly. If you have trouble with database values, you MIGHT want to set it to: com.jcorporate.expresso.core.db.DefaultEscapeHandler
skipText	Leave to true. What this does is exclude 'text' (not varchar) fields from searches. This is best for database efficiency even if your database does support searches in long text fields.

Launching and running DBCreate

Now launch your app server. Go to the expresso home page (expresso/frame.jsp), click on "Setup" and run "Create and Verify Database" this is otherwise known as DBCreate. Have all boxes checked and run it.

Troubleshooting

If DBCreate fails, take a close look at the error message. In particular, take a look at the generated SQL Expresso claims to have attempted to execute against the database. Once you isolate the issue that is causing the problems, take a look at the solutions listed below.

Table A.2. DBCreate Failure Issues

Symptoms	Cause	Solution
Weird database types. Example: Identity instead of Integer	Incorrect Database Type Mappings	Add a new database type mapping to the config file.
Invalid Primary Key Generation Statements.	Expresso is generating incorrect primary keys that your database doesn't understand.	Modify TableCreator code to create statements compatible with your database.
Create statement is failing, everything looks ok in the statement.	Check a list for your database of reserved words. Chances are either the table name or the field names are reserved for your database	Rename the offending fields or table name to something more innocuous and submit a patch to the Expresso community.

Most of the time you will need to simply adjust the type mappings on your database. To add an entry, take a look at the DBObject class that the create is failing on. Find out what type it is supposed to be and add a line to your config mapping that will look similar to this:

<type-mapping>
	<java-type>TINYINT</java-type>
	<db-type>SMALLINT</db-type>
</type-mapping>

On rare occasions, you might have to modify source code. The following are the most typical scenarios that may happen:

• Reserved Table or Field Name When porting to a new database. Often table names or field names will be reserved keywords in your database. If it is, you will have to rename either the table or the field name. Do this via a global search and replace. Submit the changes to the Expresso community so that we can have the changes included in the next major revision. To deemphasize the impact this may have, the best practice in Expresso is to use string constants in naming database field names. However, there are several areas where this switchover has not yet been completed.

• Invalid Primary Key Generation There have been several databases that have unique ways of generating primary key statements. The class com.jcorporate.expresso.core.db.TableCreator is the location where all this code is done. To patch it for your particular database, add a new if(drivername == "com.yourdatabase.Driver") { [create primary key] } type of statement.