atg.droplet.sql
Class SimpleSQLFormHandler

java.lang.Object
  atg.nucleus.logging.VariableArgumentApplicationLoggingImpl
      atg.nucleus.GenericService
          atg.droplet.EmptyFormHandler
              atg.droplet.GenericFormHandler
                  atg.droplet.sql.SimpleSQLFormHandler

All Implemented Interfaces:

DropletFormHandler, NameContextBindingListener, NameContextElement, NameResolver, AdminableService, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, atg.nucleus.logging.VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.util.EventListener

public class SimpleSQLFormHandler
extends GenericFormHandler

This form handler implements a common base class for inserting, updating, and deleting objects in a specified SQL table. This bean has a "value" property which itself has properties which represent the properties of the item being operated on by the form handler.

The bean itself is in the following states:

STATE_NOTSET

the bean does not represent a valid item in the table. any attempt to get properties of the value, returns only the properties explicitly set.

STATE_VALID

values for the key properties have been set and a query has successfully returned one or more items

STATE_INVALID

the key properties have been set, but no record was found for a lookup, update, or delete.

STATE_CONFIG_ERROR

a configuration error occurred The error conditions are:

• lookup, update, or delete when one or more specified key properties are not set
• update when no key properties are defined or when a value for a specified column property is missing.

STATE_DB_ERROR

a database error occurred

The bean supports the following submit methods:

lookup

if the key properties are set, the a query is made. If a valid item is found, the bean is marked as valid and its values are available as properties of the "value" property.

update

update the row (or rows) that correspond to the current values of the key properties

delete

removes the row (or rows) that correspond to the current value of the key properties

insert

adds a new row to the table using the current state of the value

reset

removes all properties, errors, and sets the state to STATE_NOTSET

The value property has sub-properties of its own that represent the values of columns in the current row being operated on by the form handler. For example, if you want to set or get the "firstName" column in a table, you'd reference this as "FormHandler.value.firstName" using the bean syntax.

The name of each sub-property of value should either be in the key or column lists. The list of keys is used in the lookup, update, and delete operations to define which row (or rows) should be operated on. The list of columns are used in lookup, update, and insert to specify which columns are arguments to that operation. For example, the lookup operation will retrieve the values of the column properties. The update operation will modify all columns in the table that are in the list.

The SimpleSQLFormHandler bean has the following properties:

tableName

Specifies the name of the table to operate on.

UseDataSource

This property is used to determine how to acquire database connections. If set to true, DataSource will be used to acquire database connections and DataSource and TransactionManager must be configured. If set to false or not explicitly set it will default to false and connectionURL will be used to acquire database connections.

DataSource

The DataSource used to acquire database connections if UseDataSource is set to true.

TransactionManager

The TransactionManager used to manage transactions in the case that UseDataSource is set to true.

connectionURL

The URL of the connection to use. Typically, this should be the URL of a connection pool of the form: "jdbc:atgpool:<poolName>"

keyColumns

Specifies the list of column names to use as keys to lookup, delete, and update rows.

columns

Specifies the list of column names to lookup, update, and insert. If this is not set or set to null, all columns in the table are used.

valueIndex

This property is used only in the lookup operation, when the lookup operation can retrieve more than one row. It specifies which row should be used to populate the sub-properties of the value property.

The SimpleSQLFormHandler also has a set of properties that are used to control navigation after a form operation (lookup, update, delete, insert) has been completed. These properties specify the URLs to redirect on certain error and success conditions. If the value for a particular condition is not set, the form is left on the page defined as the action for that form (i.e. no redirect takes place). Each operation has its own SuccessURL and ErrorURL properties. Thus the following properties are available:

• lookupSuccessURL
• lookupErrorURL
• updateSuccessURL
• updateErrorURL
• insertSuccessURL
• insertErrorURL
• deleteSuccessURL
• deleteErrorURL

A separate URL is used if a database error occurs when submitting the form:

• dbErrorURL

Note that these URLs are all relative to the page that is the "action" page of the form. You can either specify the values of these URLs in the .properties file of the form handler, or you can set them in the jhtml file itself using a hidden tag. For example:

  <input type=hidden bean="FormHandler.lookupErrorURL" value="/notFound.jhtml">
 

Nested Class Summary

static class	SimpleSQLFormHandler.FlexibleDoublePropertyEditor This class implements a property editor which does normal double parsing, but also check for 'true' treating it as 1.0 and 'false" as 0.0.
static class	SimpleSQLFormHandler.FlexibleIntegerPropertyEditor This class implements a property editor which does normal integer parsing, but also check for 'true' treating it as 1 and 'false" as 0.

Field Summary

static java.lang.String	CLASS_VERSION Class version string
static int	STATE_CONFIG_ERROR
static int	STATE_DB_ERROR
static int	STATE_INVALID
static int	STATE_NOTSET The constants that define the different states the form handler can be in
static int	STATE_VALID

Fields inherited from class atg.droplet.GenericFormHandler

PARAM_DEFER_FORWARD_OR_REDIRECT, PARAM_USE_FORWARDS

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

SimpleSQLFormHandler()

Method Summary

void	beforeGet(DynamoHttpServletRequest request, DynamoHttpServletResponse response) Before any form values are gotten, make sure we set any key values.
boolean	beforeSet(DynamoHttpServletRequest request, DynamoHttpServletResponse response) Before set process any form values, make sure our key columns are set from the mapping specified.
java.lang.String[]	getAllColumns()
boolean	getAutoLookup()
java.lang.String[]	getColumns()
java.lang.String	getConnectionURL()
javax.sql.DataSource	getDataSource()
java.lang.String	getDBErrorURL()
java.lang.String	getDeleteErrorURL()
java.lang.String	getDeleteSuccessURL()
java.util.Properties	getInitKeyColumnMap()
java.lang.String	getInsertErrorURL()
java.lang.String	getInsertSuccessURL()
java.lang.String[]	getKeyColumns() Returns the list of columns used as keys to determine what row to edit.
java.lang.String	getLookupErrorURL()
java.lang.String	getLookupSuccessURL()
java.lang.String	getMetaDataCatalogName() Get the catalog name
java.lang.String	getMetaDataSchemaPattern() Get the schema name pattern.
protected java.lang.String	getQualifiedTableName() A convenience method to set and retrieve the qualified table name: tablePrefix+tableName.
int	getState()
java.lang.String	getTableName()
java.lang.String	getTablePrefix() Returns property TablePrefix
javax.transaction.TransactionManager	getTransactionManager()
java.lang.String	getUpdateErrorURL()
java.lang.String	getUpdateSuccessURL()
boolean	getUseDataSource()
boolean	getValid() Returns the value of the read-only valid property.
java.util.Dictionary	getValue() Returns a dictionary of values that represent the state of the current row in the database.
boolean	handleDelete(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
boolean	handleInsert(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
boolean	handleLookup(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
boolean	handleReset(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse) This resets the state of the form handler component, clearing out the values of any properties and setting the state to STATE_NOTSET.
boolean	handleUpdate(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
void	setAutoLookup(boolean pAutoLookup) Sets the property AutoLookup.
void	setColumns(java.lang.String[] pColumns) Sets the value of the columns property.
void	setConnectionURL(java.lang.String pConnectionURL) Sets the property ConnectionURL.
void	setDataSource(javax.sql.DataSource pDataSource) Sets the DataSource
void	setDBErrorURL(java.lang.String pDBErrorURL) Sets the property DBErrorURL.
void	setDeleteErrorURL(java.lang.String pDeleteErrorURL) Sets the property DeleteErrorURL.
void	setDeleteSuccessURL(java.lang.String pDeleteSuccessURL) Sets the property DeleteSuccessURL.
void	setInitKeyColumnMap(java.util.Properties pInitKeyColumnMap) Sets the property InitKeyColumnMap.
void	setInsertErrorURL(java.lang.String pInsertErrorURL) Sets the property InsertErrorURL.
void	setInsertSuccessURL(java.lang.String pInsertSuccessURL) Sets the property InsertSuccessURL.
void	setKeyColumns(java.lang.String[] pKeyColumns) Sets the keyColumns property
void	setLookupErrorURL(java.lang.String pLookupErrorURL) Sets the property LookupErrorURL.
void	setLookupSuccessURL(java.lang.String pLookupSuccessURL) Sets the property LookupSuccessURL.
void	setMetaDataCatalogName(java.lang.String pMetaDataCatalogName) The name of a catalog, used internally only for a DatabaseMetaData.getColumns() call.
void	setMetaDataSchemaPattern(java.lang.String pMetaDataSchemaPattern) Set a string representing a schema name pattern, used internally only for a DatabaseMetaData.getColumns() call.
void	setTableName(java.lang.String pTableName) Sets the value of the tableName property.
void	setTablePrefix(java.lang.String pTablePrefix) Sets a String to be prepended as-is to the table name (tableName).
void	setTransactionManager(javax.transaction.TransactionManager pTransactionManager) Sets the TransactionManager
void	setUpdateErrorURL(java.lang.String pUpdateErrorURL) Sets the property UpdateErrorURL.
void	setUpdateSuccessURL(java.lang.String pUpdateSuccessURL) Sets the property UpdateSuccessURL.
void	setUseDataSource(boolean pUseDataSource) Sets the property UseDataSource

Methods inherited from class atg.droplet.GenericFormHandler

addFormException, addUncheckedFormException, afterSet, checkFormRedirect, createFormSubmissionMessage, getCancelURL, getCheckForValidSession, getFormError, getFormExceptions, getFormName, getMessagePort, getMessageSource, getMessageType, getPropertyExceptions, getSendMessages, getUncheckedFormExceptions, handleCancel, handleFormException, handleUncheckedFormException, hasUncheckedFormExceptions, isDeferForwardsAndRedirects, isRestorableForm, isUseForwards, isValidSession, redirectOrForward, resetFormExceptions, setCancelURL, setCheckForValidSession, setDeferForwardsAndRedirects, setFormName, setMessagePort, setMessageSource, setMessageType, setRestorableForm, setSendMessages, setUseForwards

Methods inherited from class atg.droplet.EmptyFormHandler

afterGet

Methods inherited from class atg.nucleus.GenericService

addLogListener, createAdminServlet, doStartService, doStopService, getAbsoluteName, getAdminServlet, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

STATE_NOTSET

public static final int STATE_NOTSET

The constants that define the different states the form handler can be in

See Also:

Constant Field Values

STATE_INVALID

public static final int STATE_INVALID

See Also:

Constant Field Values

STATE_VALID

public static final int STATE_VALID

See Also:

Constant Field Values

STATE_CONFIG_ERROR

public static final int STATE_CONFIG_ERROR

See Also:

Constant Field Values

STATE_DB_ERROR

public static final int STATE_DB_ERROR

See Also:

Constant Field Values

Constructor Detail

SimpleSQLFormHandler

public SimpleSQLFormHandler()

Method Detail

getKeyColumns

public java.lang.String[] getKeyColumns()

Returns the list of columns used as keys to determine what row to edit. These columns are used for all operations, but are optional for the insert operation. For lookup, update, and delete, this list of columns is used to identify the row to retrieve, update, or delete. For insert, these columns can be specified to avoid inserting a row whose key columns match an existing row. In this case a form error is generated that you can use to report this information to the user.

setKeyColumns

public void setKeyColumns(java.lang.String[] pKeyColumns)

Sets the keyColumns property

setConnectionURL

public void setConnectionURL(java.lang.String pConnectionURL)

Sets the property ConnectionURL.

getConnectionURL

public java.lang.String getConnectionURL()

Returns:

The value of the property ConnectionURL.

getColumns

public java.lang.String[] getColumns()

Returns:

the value of the columns property. This specifies the list of column names that are used in the lookup, update, and insert operations.

setColumns

public void setColumns(java.lang.String[] pColumns)

Sets the value of the columns property. This specifies the list of the column names that are used in the lookup, update, and insert operations.

getAllColumns

public java.lang.String[] getAllColumns()

Returns:

the list of all columns that this form handler uses including both the keyColumns and the columns. If a column appears in both lists, it will only appear in this list once.

getTableName

public java.lang.String getTableName()

Returns:

the value of the tableName property.

setTableName

public void setTableName(java.lang.String pTableName)

Sets the value of the tableName property. This specifies the name of the table to be used by the lookup, update, delete, and insert operations

getValue

public java.util.Dictionary getValue()

Returns a dictionary of values that represent the state of the current row in the database. These values are split into two groups: those in the keyColumns list, and those in the columns list. The keyColumn properties are used to lookup the row to perform either the lookup, update, or delete operations. The columns properties are the columns that are looked up by the lookup operation, updated by the update operation and inserted by the insert operation.

setAutoLookup

public void setAutoLookup(boolean pAutoLookup)

Sets the property AutoLookup. If this property is true, the form handler will automatically do a "lookup" when you attempt to get a property of a value without having done an update, insert, or delete after having set some sub-properties of value.

getAutoLookup

public boolean getAutoLookup()

Returns:

The value of the property AutoLookup.

setInitKeyColumnMap

public void setInitKeyColumnMap(java.util.Properties pInitKeyColumnMap)

Sets the property InitKeyColumnMap. This property can be used to initialize the values of key columns from nucleus properties. You can provide one entry with the key set to the name of the key column, and the value set to the absolute path name of the property you want to initialize it to. For example, to initialize a key value from a parameter in the request, you'd say: myKeyName=/OriginatingRequest.myParamName where myKeyName is the name of an entry in your keyColumns list and myParamName is the name of a parameter in the current request.

The key values are set in the beforeSet and/or beforeGet methods as called by the droplets system for form submission and form rendering respectively.

getInitKeyColumnMap

public java.util.Properties getInitKeyColumnMap()

Returns:

The value of the property InitKeyColumnMap.

setLookupSuccessURL

public void setLookupSuccessURL(java.lang.String pLookupSuccessURL)

Sets the property LookupSuccessURL.

getLookupSuccessURL

public java.lang.String getLookupSuccessURL()

Returns:

The value of the property LookupSuccessURL.

setUpdateSuccessURL

public void setUpdateSuccessURL(java.lang.String pUpdateSuccessURL)

Sets the property UpdateSuccessURL.

getUpdateSuccessURL

public java.lang.String getUpdateSuccessURL()

Returns:

The value of the property UpdateSuccessURL.

setDeleteSuccessURL

public void setDeleteSuccessURL(java.lang.String pDeleteSuccessURL)

Sets the property DeleteSuccessURL.

getDeleteSuccessURL

public java.lang.String getDeleteSuccessURL()

Returns:

The value of the property DeleteSuccessURL.

setInsertSuccessURL

public void setInsertSuccessURL(java.lang.String pInsertSuccessURL)

Sets the property InsertSuccessURL.

getInsertSuccessURL

public java.lang.String getInsertSuccessURL()

Returns:

The value of the property InsertSuccessURL.

setLookupErrorURL

public void setLookupErrorURL(java.lang.String pLookupErrorURL)

Sets the property LookupErrorURL.

getLookupErrorURL

public java.lang.String getLookupErrorURL()

Returns:

The value of the property LookupErrorURL.

setUpdateErrorURL

public void setUpdateErrorURL(java.lang.String pUpdateErrorURL)

Sets the property UpdateErrorURL.

getUpdateErrorURL

public java.lang.String getUpdateErrorURL()

Returns:

The value of the property UpdateErrorURL.

setDeleteErrorURL

public void setDeleteErrorURL(java.lang.String pDeleteErrorURL)

Sets the property DeleteErrorURL.

getDeleteErrorURL

public java.lang.String getDeleteErrorURL()

Returns:

The value of the property DeleteErrorURL.

setInsertErrorURL

public void setInsertErrorURL(java.lang.String pInsertErrorURL)

Sets the property InsertErrorURL.

getInsertErrorURL

public java.lang.String getInsertErrorURL()

Returns:

The value of the property InsertErrorURL.

setDBErrorURL

public void setDBErrorURL(java.lang.String pDBErrorURL)

Sets the property DBErrorURL.

getDBErrorURL

public java.lang.String getDBErrorURL()

Returns:

The value of the property DBErrorURL.

setUseDataSource

public void setUseDataSource(boolean pUseDataSource)

Sets the property UseDataSource

getUseDataSource

public boolean getUseDataSource()

Returns:

The value of the property UseDataSource.

setDataSource

public void setDataSource(javax.sql.DataSource pDataSource)

Sets the DataSource

getDataSource

public javax.sql.DataSource getDataSource()

Returns:

The value of the property DataSource.

setTransactionManager

public void setTransactionManager(javax.transaction.TransactionManager pTransactionManager)

Sets the TransactionManager

getTransactionManager

public javax.transaction.TransactionManager getTransactionManager()

Returns:

The value of the property TransactionManager.

setMetaDataCatalogName

public void setMetaDataCatalogName(java.lang.String pMetaDataCatalogName)

The name of a catalog, used internally only for a DatabaseMetaData.getColumns() call. If this is null (the default), then we query the Connection for this information.

Parameters:

String - the name of a catalog

See Also:

DatabaseMetaData

getMetaDataCatalogName

public java.lang.String getMetaDataCatalogName()

Get the catalog name

Returns:

the catalog name

setMetaDataSchemaPattern

public void setMetaDataSchemaPattern(java.lang.String pMetaDataSchemaPattern)

Set a string representing a schema name pattern, used internally only for a DatabaseMetaData.getColumns() call. If this is null (the default), then we query the Connection for this information.

Parameters:

String - the schema name

See Also:

DatabaseMetaData

getMetaDataSchemaPattern

public java.lang.String getMetaDataSchemaPattern()

Get the schema name pattern.

Returns:

the schema name

setTablePrefix

public void setTablePrefix(java.lang.String pTablePrefix)

Sets a String to be prepended as-is to the table name (tableName). If it is not null (the default), it is used in constructing the SQL for all queries except for internal DatabaseMetaData calls, where metaDataSchemaPattern and metaDataCatalogName are used instead. For instance, say Dynamo is connecting to the database as the account "user"; but the table being accessed actually belongs to the account "adm". Account "adm" has granted "user" select, insert, delete, and update privileges, but has not granted create privileges. In order for SimpleSQLFormHandler to behave properly in this situation, we need to set two properties in the form handler component:

• metaDataSchemaPattern=adm
• tablePrefix=adm.

Note that the dot at the end of "adm." is part of the string being assigned. The metaDataSchemaPattern is used by internal getMetaData calls. The tablePrefix is used in constructing all the SQL that is used by the form handler. Why two properties? This is necessary because some databases require an explicit schema.table pattern for, say, inserting on a table not owned by the user. Other databases provide a synonym object. Still other databases have a different punctuation mark than '.'

Parameters:

String - the prefix to be prepended to tableName

getTablePrefix

public java.lang.String getTablePrefix()

Returns property TablePrefix

getQualifiedTableName

protected java.lang.String getQualifiedTableName()

A convenience method to set and retrieve the qualified table name: tablePrefix+tableName.

Returns:

either the simple table name, or "tablePrefix+tableName" (no punctuation is inserted), or null if tableName is null.

beforeSet

public boolean beforeSet(DynamoHttpServletRequest request,
                         DynamoHttpServletResponse response)
                  throws DropletFormException

Before set process any form values, make sure our key columns are set from the mapping specified.

Specified by:

beforeSet in interface DropletFormHandler

Overrides:

beforeSet in class GenericFormHandler

Returns:

true if form processing should continue, false if it should be aborted

Throws:

DropletFormException

beforeGet

public void beforeGet(DynamoHttpServletRequest request,
                      DynamoHttpServletResponse response)

Before any form values are gotten, make sure we set any key values.

Specified by:

beforeGet in interface DropletFormHandler

Overrides:

beforeGet in class EmptyFormHandler

handleLookup

public boolean handleLookup(DynamoHttpServletRequest pRequest,
                            DynamoHttpServletResponse pResponse)
                     throws javax.servlet.ServletException,
                            java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

handleDelete

public boolean handleDelete(DynamoHttpServletRequest pRequest,
                            DynamoHttpServletResponse pResponse)
                     throws javax.servlet.ServletException,
                            java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

handleUpdate

public boolean handleUpdate(DynamoHttpServletRequest pRequest,
                            DynamoHttpServletResponse pResponse)
                     throws javax.servlet.ServletException,
                            java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

handleInsert

public boolean handleInsert(DynamoHttpServletRequest pRequest,
                            DynamoHttpServletResponse pResponse)
                     throws javax.servlet.ServletException,
                            java.io.IOException

Throws:

javax.servlet.ServletException

java.io.IOException

handleReset

public boolean handleReset(DynamoHttpServletRequest pRequest,
                           DynamoHttpServletResponse pResponse)
                    throws javax.servlet.ServletException,
                           java.io.IOException

This resets the state of the form handler component, clearing out the values of any properties and setting the state to STATE_NOTSET.

Throws:

javax.servlet.ServletException

java.io.IOException

getState

public int getState()

getValid

public boolean getValid()

Returns the value of the read-only valid property. This property is set to true if the most recent operation (lookup, update, insert, or deleted was successfully completed) leaving the sub-properties of the value property in a valid state.