org.apache.cocoon.acting.modular
Class DatabaseAction

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.acting.AbstractAction
          org.apache.cocoon.acting.AbstractConfigurableAction
              org.apache.cocoon.acting.ConfigurableServiceableAction
                  org.apache.cocoon.acting.AbstractComplementaryConfigurableAction
                      org.apache.cocoon.acting.modular.DatabaseAction

All Implemented Interfaces:

Disposable, Component, Configurable, LogEnabled, Serviceable, ThreadSafe, Action

Direct Known Subclasses:

DatabaseAddAction, DatabaseDeleteAction, DatabaseQueryAction, DatabaseSelectAction, DatabaseUpdateAction

public abstract class DatabaseAction
extends AbstractComplementaryConfigurableAction
implements Disposable, ThreadSafe

Abstract action for common function needed by database actions. The difference to the other Database*Actions is, that the actions in this package use additional components ("modules") for reading and writing parameters. In addition the descriptor format has changed to accomodate the new features.

This action is heavily based upon the original DatabaseAddActions.

Modes have to be configured in cocoon.xconf. Mode names from descriptor.xml file are looked up in the component service. Default mode names can only be set during action setup.

The number of affected rows is returned to the sitemap with the "row-count" parameter if at least one row was affected.

All known column types can be found in JDBCTypeConversions.

Configuration options (setup):
input	default mode name for reading values (request-param)
autoincrement	default mode name for obtaining values from autoincrement columns (auto)
append-row	append row number in square brackets to column name for output (yes)
append-table-name	add table name to column name for both in- and output (yes)
first-row	row index of first row (0)
path-separator	string to separate table name from column name (.)

Configuration options (setup and per invocation):
throw-exception	throw an exception when an error occurs (default: false)
descriptor	file containing database description
table-set	table-set name to work with
output	mode name for writing values (request-attr)
reloadable	dynamically reload descriptor file if change is detected
use-transactions	defaults to yes
connection	configured datasource connection to use (overrides value from descriptor file)
fail-on-empty	(boolean) fail is statement affected zero rows (true)

Version:

$Id: DatabaseAction.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Christian Haul

See Also:

org.apache.cocoon.components.modules.input, org.apache.cocoon.components.modules.output, org.apache.cocoon.components.modules.database, JDBCTypeConversions

Nested Class Summary

protected static class	DatabaseAction.CacheHelper Structure that takes all processed data for a table depending on current default modes
protected static class	DatabaseAction.Column Structure that takes all processed data for one column.
protected static class	DatabaseAction.LookUpKey Structure that takes up both current mode types for database operations and table configuration data.

Field Summary

protected HashMap	cachedQueryData
protected ServiceSelector	dbselector
protected Map	defaultModeNames
protected boolean	failOnEmpty
protected int	firstRow
protected String	pathSeparator

Fields inherited from class org.apache.cocoon.acting.ConfigurableServiceableAction

manager

Fields inherited from class org.apache.cocoon.acting.AbstractConfigurableAction

settings

Fields inherited from class org.apache.cocoon.acting.AbstractAction

EMPTY_MAP

Fields inherited from interface org.apache.cocoon.acting.Action

ROLE

Constructor Summary

DatabaseAction()

Method Summary

Map	act(Redirector redirector, SourceResolver resolver, Map objectModel, String source, Parameters param) Add a record to the database.
void	configure(Configuration conf) Configures the Action.
void	dispose() dispose
protected void	fillModes(Configuration[] conf, boolean isKey, Map defaultModeNames, Map modeTypes, DatabaseAction.CacheHelper set) Setup parsed attribute configuration object
protected Object[]	getColumnValue(Configuration tableConf, DatabaseAction.Column column, Map objectModel)
protected DataSourceComponent	getDataSource(Configuration conf, Parameters parameters) Get the Datasource we need.
protected Configuration	getMode(Configuration conf, String type) Choose a mode configuration based on its name.
protected String	getOutputName(Configuration tableConf, Configuration columnConf) compose name for output a long the lines of "table.column"
protected String	getOutputName(Configuration tableConf, Configuration columnConf, int rowIndex) compose name for output a long the lines of "table.column[row]" or "table.column" if rowIndex is -1.
protected abstract DatabaseAction.CacheHelper	getQuery(Configuration table, Map modeTypes, Map defaultModeNames) Get the String representation of the PreparedStatement.
protected abstract boolean	honourAutoIncrement() determine whether autoincrement columns should be honoured by this operation.
protected boolean	isLargeObject(String type) Return whether a type is a Large Object (BLOB/CLOB).
protected abstract int	processRow(Map objectModel, Connection conn, PreparedStatement statement, String outputMode, Configuration table, DatabaseAction.CacheHelper queryData, Object[][] columnValues, int rowIndex, Map results) set all necessary ?
protected int	processTable(Configuration table, Connection conn, Map objectModel, Map results, Map modeTypes) Inserts a row or a set of rows into the given table based on the request parameters
protected abstract String	selectMode(boolean isAutoIncrement, Map modes) determine which mode to use as default mode This method is intended to be overridden by classes that implement other operations e.g. delete
void	service(ServiceManager manager) Compose the Actions so that we can select our databases.
protected void	setColumn(Map objectModel, String outputMode, Map results, Configuration table, Configuration column, int rowIndex, Object value, PreparedStatement statement, int position) set a column in a statement using the appropriate JDBC setXXX method and propagate the value to the output module and results map if present.
protected void	setColumn(PreparedStatement statement, int position, Configuration entry, Object value) set a column in a statement using the appropriate JDBC setXXX method.
protected void	setOutput(Map objectModel, String outputMode, Map results, Configuration table, Configuration column, int rowIndex, Object value) create a unique name using the getOutputName method and write the value to the output module and the results map if present.
protected void	setOutputAttribute(Map objectModel, String outputMode, String key, Object value) Store a key/value pair in the output attributes.

Methods inherited from class org.apache.cocoon.acting.AbstractComplementaryConfigurableAction

getConfiguration, getConfiguration, getConfiguration

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

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

Field Detail

dbselector

protected ServiceSelector dbselector

defaultModeNames

protected Map defaultModeNames

cachedQueryData

protected final HashMap cachedQueryData

pathSeparator

protected String pathSeparator

firstRow

protected int firstRow

failOnEmpty

protected boolean failOnEmpty

Constructor Detail

DatabaseAction

public DatabaseAction()

Method Detail

configure

public void configure(Configuration conf)
               throws ConfigurationException

Description copied from class: AbstractConfigurableAction

Configures the Action. Takes the children from the Configuration and stores them them as key (configuration name) and value (configuration value) in settings.
This automates parsing of flat string-only configurations. For nested configurations, override this function in your action.

Specified by:

configure in interface Configurable

Overrides:

configure in class AbstractConfigurableAction

Throws:

ConfigurationException

service

public void service(ServiceManager manager)
             throws ServiceException

Compose the Actions so that we can select our databases.

Specified by:

service in interface Serviceable

Overrides:

service in class ConfigurableServiceableAction

Throws:

ServiceException

dispose

public void dispose()

dispose

Specified by:

dispose in interface Disposable

getDataSource

protected DataSourceComponent getDataSource(Configuration conf,
                                            Parameters parameters)
                                     throws ServiceException

Get the Datasource we need.

Throws:

ServiceException

isLargeObject

protected final boolean isLargeObject(String type)

Return whether a type is a Large Object (BLOB/CLOB).

setOutputAttribute

protected void setOutputAttribute(Map objectModel,
                                  String outputMode,
                                  String key,
                                  Object value)

Store a key/value pair in the output attributes. We prefix the key with the name of this class to prevent potential name collisions.

processTable

protected int processTable(Configuration table,
                           Connection conn,
                           Map objectModel,
                           Map results,
                           Map modeTypes)
                    throws SQLException,
                           ConfigurationException,
                           Exception

Inserts a row or a set of rows into the given table based on the request parameters

Parameters:

table - the table's configuration

conn - the database connection

objectModel - the objectModel

Throws:

SQLException

ConfigurationException

Exception

getMode

protected Configuration getMode(Configuration conf,
                                String type)
                         throws ConfigurationException

Choose a mode configuration based on its name.

Parameters:

conf - Configuration (i.e. a column's configuration) that might have several children configurations named "mode".

type - desired type (i.e. every mode has a type attribute), find the first mode that has a compatible type. Special mode "all" matches all queried types.

Returns:

configuration that has desired type or type "all" or null.

Throws:

ConfigurationException

getOutputName

protected String getOutputName(Configuration tableConf,
                               Configuration columnConf)

compose name for output a long the lines of "table.column"

getOutputName

protected String getOutputName(Configuration tableConf,
                               Configuration columnConf,
                               int rowIndex)

compose name for output a long the lines of "table.column[row]" or "table.column" if rowIndex is -1. If the section of the sitemap corresponding to the action contains false the name for output is "column[row]" If the section of the sitemap corresponding to the action contains false the name for output is "column"

getColumnValue

protected Object[] getColumnValue(Configuration tableConf,
                                  DatabaseAction.Column column,
                                  Map objectModel)
                           throws ConfigurationException,
                                  ServiceException

Throws:

ConfigurationException

ServiceException

fillModes

protected void fillModes(Configuration[] conf,
                         boolean isKey,
                         Map defaultModeNames,
                         Map modeTypes,
                         DatabaseAction.CacheHelper set)
                  throws ConfigurationException

Setup parsed attribute configuration object

Throws:

ConfigurationException

setOutput

protected void setOutput(Map objectModel,
                         String outputMode,
                         Map results,
                         Configuration table,
                         Configuration column,
                         int rowIndex,
                         Object value)

create a unique name using the getOutputName method and write the value to the output module and the results map if present.

setColumn

protected void setColumn(PreparedStatement statement,
                         int position,
                         Configuration entry,
                         Object value)
                  throws Exception

set a column in a statement using the appropriate JDBC setXXX method.

Throws:

Exception

setColumn

protected void setColumn(Map objectModel,
                         String outputMode,
                         Map results,
                         Configuration table,
                         Configuration column,
                         int rowIndex,
                         Object value,
                         PreparedStatement statement,
                         int position)
                  throws Exception

set a column in a statement using the appropriate JDBC setXXX method and propagate the value to the output module and results map if present. Effectively combines calls to setColumn and setOutput.

Throws:

Exception

act

public Map act(Redirector redirector,
               SourceResolver resolver,
               Map objectModel,
               String source,
               Parameters param)
        throws Exception

Add a record to the database. This action assumes that the file referenced by the "descriptor" parameter conforms to the AbstractDatabaseAction specifications.

Specified by:

act in interface Action

resolver - The SourceResolver in charge

objectModel - The Map with object of the calling environment which can be used to select values this controller may need (ie Request, Response).

source - A source String to the Action

param - The Parameters for this invocation

Returns:

Map The returned Map object with sitemap substitution values which can be used in subsequent elements attributes like src= using a xpath like expression: src="mydir/{myval}/foo" If the return value is null the processing inside the element of the sitemap will be skipped.

Throws:

Exception - Indicates something is totally wrong

processRow

protected abstract int processRow(Map objectModel,
                                  Connection conn,
                                  PreparedStatement statement,
                                  String outputMode,
                                  Configuration table,
                                  DatabaseAction.CacheHelper queryData,
                                  Object[][] columnValues,
                                  int rowIndex,
                                  Map results)
                           throws SQLException,
                                  ConfigurationException,
                                  Exception

set all necessary ?s and execute the query return number of rows processed This method is intended to be overridden by classes that implement other operations e.g. delete

Throws:

SQLException

ConfigurationException

Exception

selectMode

protected abstract String selectMode(boolean isAutoIncrement,
                                     Map modes)

determine which mode to use as default mode This method is intended to be overridden by classes that implement other operations e.g. delete

honourAutoIncrement

protected abstract boolean honourAutoIncrement()

determine whether autoincrement columns should be honoured by this operation. This is usually snsible only for INSERTs. This method is intended to be overridden by classes that implement other operations e.g. delete

getQuery

protected abstract DatabaseAction.CacheHelper getQuery(Configuration table,
                                                       Map modeTypes,
                                                       Map defaultModeNames)
                                                throws ConfigurationException,
                                                       ServiceException

Get the String representation of the PreparedStatement. This is mapped to the Configuration object itself, so if it doesn't exist, it will be created. This method is intended to be overridden by classes that implement other operations e.g. delete

Parameters:

table - the table's configuration object

Returns:

the insert query as a string

Throws:

ConfigurationException

ServiceException