com.perdues.db
Class Form

java.lang.Object
  |
  +--com.perdues.web.HTForm
        |
        +--com.perdues.db.Form

public class Form

extends HTForm

This class extends HTForm with methods to read, insert, update, and delete records in a SQL database, and to validate data entered in an HTML form for insert or update of a database record. All of these methods automatically match Form fields with database fields with corresponding names. Database reads also do simple joins automatically based on identified foreign keys.

Validation uses extended database schema information that can include application types such as email, date, phone number, and so on.

Some of the methods associate database fields with form fields. Dots in qualified database field names match with double-underscores in the form field name.

Field Summary

static boolean

debug

Constructor Summary

Form(Form form)
Makes a new Form that is a copy of an existing one.

Form(javax.servlet.http.HttpServletRequest request, Schema schema)
A form gets its initial state from the parameters in the request.

Form(Schema schema)
Constructs an empty Form.

Method Summary

void	delete(java.lang.String tableName, java.sql.Connection conn) Deletes the record determined by this form, using the given database connection.
void	insert(java.lang.String tableName, java.sql.Connection conn) Inserts a new record into the database using data from the form.
void	read(java.lang.String table, java.sql.Connection conn) Reads a row of data from the named table into this Form via the given JDBC connection.
void	read(java.lang.String tableName, java.sql.Connection conn, java.lang.String[] fields, java.lang.String[] extras) Reads a row of data from the named table into this Form via the given JDBC connection.
boolean	update(java.lang.String tableName, java.sql.Connection conn) Updates a record from a form.
java.util.Hashtable	validate(java.lang.String tableName) Checks all fields of the form according to the type specified for the relevant column of this table.
void	validate(java.lang.String tableName, java.util.Hashtable errs) A form of validate that takes a Hashtable as input and adds any error messages to it.
void	validate(java.lang.String tableName, java.util.Hashtable errs, java.lang.String[] fields) A form of validate that takes a Hashtable as input and adds any error messages to it.
java.util.Hashtable	validate(java.lang.String tableName, java.lang.String[] fields) Validates this Form using extended schema information.

Methods inherited from class com.perdues.web.HTForm

addValue, getCheckbox, getCheckbox, getCheckboxes, getCheckboxes, getChoice, getChoice, getDate, getDateField, getHidden, getInt, getInt, getList, getList, getOptions, getPassword, getRadios, getText, getTextarea, getTextarea, getTextfield, getValue, getValue, getValue, getValues, has, hasValue, keys, mergeForm, mergePathInfo, removeValue, removeValue, setDate, setDefault, setValue, setValues, splitString, toQueryString, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

debug

public static boolean debug

Constructor Detail

Form

public Form(javax.servlet.http.HttpServletRequest request,
            Schema schema)

A form gets its initial state from the parameters in the request.

Form

public Form(Schema schema)

Constructs an empty Form.

Form

public Form(Form form)

Makes a new Form that is a copy of an existing one.

Method Detail

read

public void read(java.lang.String table,
                 java.sql.Connection conn)

Reads a row of data from the named table into this Form via the given JDBC connection. This operation relies on extended schema information. This Form must already contain a binding for the primary key of the named table, and that value determines which row this reads. Reads all fields of the table, but will not auto-join.

FIXME: Currently doesn't return anything.

read

public void read(java.lang.String tableName,
                 java.sql.Connection conn,
                 java.lang.String[] fields,
                 java.lang.String[] extras)

Reads a row of data from the named table into this Form via the given JDBC connection. This operation relies on extended schema information. This Form must already contain a binding for the primary key of the named table, and that value determines which row this reads. This only fills fields named in the "fields" array, but may automatically join the table through foreign key fields to access associated values from other tables.

validate

public java.util.Hashtable validate(java.lang.String tableName)

Checks all fields of the form according to the type specified for the relevant column of this table. As usual, each form field is matched with the column that has the same name. Returns a hashtable that maps from the full name of any column that is invalid, to an error message which is a sentence without a subject. The error message displayer has the responsibility of filling in the subject.

Only checks form fields with names matching column names of the table. In some applications you may wish to first set default values into the form where appropriate.

Delegates checking of individual columns to the ColumnInfo.validate method, passing in the column's name as the form's fieldname. The type's validation method should not give an error if the field is "logically absent" from the form.

validate

public java.util.Hashtable validate(java.lang.String tableName,
                                    java.lang.String[] fields)

Validates this Form using extended schema information. Checks fields that are present in the Form and match database field names in the list. Returns a Hashtable of validation information.

validate

public void validate(java.lang.String tableName,
                     java.util.Hashtable errs)

A form of validate that takes a Hashtable as input and adds any error messages to it. Any newly-added error for a column overrides an existing entry.

validate

public void validate(java.lang.String tableName,
                     java.util.Hashtable errs,
                     java.lang.String[] fields)

A form of validate that takes a Hashtable as input and adds any error messages to it. Any newly-added error for a column overrides an existing entry.

insert

public void insert(java.lang.String tableName,
                   java.sql.Connection conn)

Inserts a new record into the database using data from the form. Fields with no value in the form, and fields for which the renderForSQL method fails by returning null, are omitted from the field insertion list. Corresponding Form fields should have the simple name of the column.

If the table has a primary key, this sets the corresponding form field to the database's "last insert ID" based on the possibility that it might be an autoincrement column.

Contains policy that any column named "registration" or "last_update" will be set to today's date on insert. TODO: This policy should be handled by extended schema info rather than column name.

update

public boolean update(java.lang.String tableName,
                      java.sql.Connection conn)

Updates a record from a form. Automatically modifies any fields named "last_update". TODO: (This policy should really be established by schema information instead.) Columns where renderForSQL returns null do not appear in the generated update statement.

Enhancements for updateRecord and insertRecord: These should be extended with table-specific hooks to perform additional actions such as updating lists of opportunity categories. They could be enhanced to directly support updating of relationship tables, e.g. opportunity categories.

Returns true unless no such record exists.

delete

public void delete(java.lang.String tableName,
                   java.sql.Connection conn)

Deletes the record determined by this form, using the given database connection. Uses the given table's primary key to determine which record to delete.