You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by as...@apache.org on 2007/09/08 22:17:47 UTC
svn commit: r573901 [19/44] - in /cocoon/site: site/ site/2.0/
site/2.0/developing/ site/2.0/faq/ site/2.0/howto/chaperon/
site/2.0/installing/ site/2.0/plan/ site/2.0/snippet/ site/2.0/tutorial/
site/2.0/userdocs/ site/2.0/userdocs/actions/ site/2.0/u...
Modified: cocoon/site/site/2.0/userdocs/actions/database-actions.html
URL: http://svn.apache.org/viewvc/cocoon/site/site/2.0/userdocs/actions/database-actions.html?rev=573901&r1=573900&r2=573901&view=diff
==============================================================================
--- cocoon/site/site/2.0/userdocs/actions/database-actions.html (original)
+++ cocoon/site/site/2.0/userdocs/actions/database-actions.html Sat Sep 8 13:17:41 2007
@@ -1,753 +1,753 @@
-<html>
-<head>
-<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<title>Database Actions</title>
-<STYLE type="text/css">
-a.menu {
- color: #FFFFFF;
- text-align:left;
- font-size:12px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:plain;
- text-decoration:none;
- padding-left: 14px
-}
-
-A.menu:hover {
- color: #FFCC00
-}
-
-
-.menutitle {
- color: #000000;
- text-align:left;
- font-size:10px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:bold;
- padding-left: 8px
-}
-.menuselected {
- color: #FFCC00;
- text-align:left;
- font-size:12px;
- font-family: Verdana, Arial, Helvetica, sans-serif;
- font-weight:bold;
- padding-left: 14px
-}
-</STYLE>
-</head>
-<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
-<table border="0" cellpadding="0" cellspacing="0" width="100%">
-<tr>
-<td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
-</tr>
-<tr>
-<td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Database Actions</font></td>
-</tr>
-<tr>
-<td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
-<table width="288" cellspacing="0" cellpadding="0" border="0">
-<tr>
-<td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
-</tr>
-</table>
-</td>
-</tr>
-</table>
-<table width="100%" cellspacing="0" cellpadding="0" border="0">
-<tr width="100%">
-<td align="left" valign="top" width="120">
-<table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
-<tr>
-<td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
-</td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">User Documentation</a></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">Actions</span></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="actions.html">Overview</a></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Database</span></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">Default</span></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">Core</span></td>
-</tr>
-<tr>
-<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
-<span class="menutitle">Optional</span></td>
-</tr>
-<tr>
-<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session-action.html">Session Action</a></td>
-</tr>
-<tr>
-<td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
-</td>
-</tr>
-</table>
-</td><td>
-<table cellspacing="15" cellpadding="0" border="0">
-<tr>
-<td>
-
-
-
-
- <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Two different sets of actions exist, that deal with (object) relational
- database access through JDBC. The original database actions provide a
- relatively simple interface to store, modify, delete and retrieve data.
- They are oriented towards usage of request parameters for input and
- request attributes together with sitemap variables for output and do
- not support auto increment column types. In addition, the description of
- the database structure is split over several files since these actions
- attempt to use all tables in a provided description.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The modular database actions provide similar functionality. In contrast
- to the original actions they allow to store the database meta data in a
- single file and to switch input and output flexible through the use of
- modules. Even for auto increment columns specific modules exist that
- cover a wide range of database management systems.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For an overview of column types supported by the modular database
- actions, see javadocs for JDBCTypeConversions. The types supported by
- the original actions are documented in AbstractDatabaseAction.
- </font>
-</p>
-
-
-
-<font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Original Database Actions</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The original database actions have evolved quite a bit and at different
- speeds. The add action is certainly the most complete one, providing
- support for multiple tables and rows. However, the interface has become
- a bit inconsistent.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- If an error occurs, the original database actions will throw an
- exception.
- </font>
-</p>
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Describing the Structure of your DB - descriptor.xml</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The key to database actions is a file that describes database meta
- data in XML. The original actions will ignore all but the first table
- and act only on one row. Only the add action will try to access all
- tables that are contained in this description. As a consequence, each
- HTML form needs to have a corresponding descriptor file if different
- tables are affected.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The file name has no meaning and does not need to be
- <code><font face="courier, monospaced">descriptor.xml</font></code> - it can even be a Cocoon pipeline. The
- name of the root element in a descriptor file is ignored. Only
- <code><font face="courier, monospaced">table</font></code> elements nested on first level inside the root
- element are parsed by the actions. All unknown elements or attributes
- are ignored.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For each table a <code><font face="courier, monospaced">table</font></code> element needs to be present.
- </font>
-</p>
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-
-<?xml version="1.0"?>
-
-<employee>
- <connection>personnel</connection>
- <table name="employee">
- <keys>
- <key param="employee" dbcol="id" type="int" mode="manual"/>
- </keys>
- <values>
- <value param="name" dbcol="name" type="string"/>
- <value param="department" dbcol="department_id" type="int"/>
- </values>
- </table>
-</employee>
-
- </pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Describes a single table named "employee". In addition a database
- connection is specified. See <a href="../../developing/datasources.html">here</a> for more
- information on database connections.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Key Columns</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Tables may or may not have key columns. A key column is a column
- that is part of the primary key. Actually, candidate keys should do
- as well.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- All key columns are contained in a <code><font face="courier, monospaced">keys</font></code> child element
- of the <code><font face="courier, monospaced">table</font></code> element. Each column has a
- <code><font face="courier, monospaced">key</font></code> element to define its properties. The
- <code><font face="courier, monospaced">dbcol</font></code> attribute holds the column name,
- <code><font face="courier, monospaced">type</font></code> is the JDBC type name for this column (have a
- look at AbstactDatabaseAction source for valid type names),
- <code><font face="courier, monospaced">param</font></code> specifies the name of the request parameter to
- use, and <code><font face="courier, monospaced">mode</font></code> sets how the value for this column is
- obtained on adding a row.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Through the mode attribute the behaviour of the add action can be
- changed.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Default mode is "automatic" and to let the database create the key
- value by setting this value to <code><font face="courier, monospaced">null</font></code>. The created value
- can not be read back from the database and will not be available as
- request attribute or sitemap variable.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A mode of "manual" will query the database for the maximum current
- value, add 1 to it and use that for a value.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A mode of "form" will use the corresponding request parameter.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- A mode of "request-attribute" will use the corresponding request
- attribute. The name specified in the <code><font face="courier, monospaced">param</font></code> attribute
- will be automatically prefixed with the class name.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Key values will be propagated to sitemap variables and - prefixed
- with the class name - request attributes.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Other Columns</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- All other columns are contained in a <code><font face="courier, monospaced">values</font></code> child
- element of the <code><font face="courier, monospaced">table</font></code> element. Each column has a
- <code><font face="courier, monospaced">value</font></code> element to define its properties. Properties are
- similar to those for key columns. A <code><font face="courier, monospaced">mode</font></code> attribute
- does not exist for value columns. Instead, request parameters and
- request attributes are tried in this order for the specified
- parameter.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Request attribute names are <i>not</i> prefixed with the class
- name. Thus, to insert the value of a key column of the previous row
- or previous table into a value column, it needs to be named
- <code><font face="courier, monospaced">org.apache.cocoon.acting.AbstractDatabaseAction:key:table:dbcol</font></code>.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Value columns are propagated to request attributes with class name
- prefix. They are not available for the sitemap.
- </font>
-</p>
-
-
-
-
-<font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Modular Database Actions</font>
-<hr style="color: #0086b2" size="1">
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The modular database actions were mainly created to make auto increment
- columns available, handle input and output flexibly, and have a
- consistent interface. A successful action will return the number of
- rows affected in a sitemap parameter named <code><font face="courier, monospaced">row-count</font></code>. The
- added features required to change the descriptor file format in
- incompatible ways.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- It can be configured if an exception will be thrown when an error
- occurs.
- </font>
-</p>
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Describing the Structure of your DB - descriptor.xml</b></font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Like the original actions, the modular actions need meta data in an
- XML file. However, that file may contain any number of tables, not
- just the ones needed for a single request. The tables actually used
- are referenced through a <code><font face="courier, monospaced">table-set</font></code>. Unknown elements and
- attributes are ignored. This way a descriptor file can be shared with
- other actions like the form validator.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- For the flexible input and output handling, the modular database
- actions rely on <a href="../concepts/modules.html">modules</a>.
- Have a look at those before proceeding.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The following is a snippet from a descriptor file.
- </font>
-</p>
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-
-<root>
- <connection>personnel</connection>
- <table name="user" alias="user">
- <keys>
- <key name="uid" type="int" autoincrement="true">
- <mode name="auto" type="autoincr"/>
- </key>
- </keys>
- <values>
- <value name="name" type="string"></value>
- <value name="firstname" type="string"></value>
- <value name="uname" type="string"></value>
- </values>
- </table>
-
- </pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The <code><font face="courier, monospaced">table</font></code> element has an additional attribute
- <code><font face="courier, monospaced">alias</font></code> which is an alternative name to reference
- the table from a table set. The descriptor file is searched
- top down for tables whose <code><font face="courier, monospaced">name</font></code> or
- <code><font face="courier, monospaced">alias</font></code> match. The <code><font face="courier, monospaced">alias</font></code>n attribute
- is useful if a complex join expression is used as table
- name. In such a case modifications like update, insert,
- delete will likely fail.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Another application of aliases if different numbers of columns should
- be affected by an operation. or if a table contains several candidate
- keys that are used alternatively. This way, different views to a
- table can be created.
- </font>
-</p>
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Key Columns</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The descriptor file resembles the one for the original actions. One
- major difference is the absence of <code><font face="courier, monospaced">dbcol</font></code> and
- <code><font face="courier, monospaced">param</font></code> attributes. Instead there is a <code><font face="courier, monospaced">name</font></code>
- attribute which corresponds to the <code><font face="courier, monospaced">dbcol</font></code> attribute and
- specifies the database column name.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- If a column is an auto increment column, the similar named attribute
- indicates this. Auto increment columns will be handled differently
- on insert operations.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Instead of specifying a parameter name, the actions support to use
- different input modules for each operation through the nested
- <code><font face="courier, monospaced">mode</font></code> elements. This is described in more detail below.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Note here though, that not every column needs a <code><font face="courier, monospaced">mode</font></code>
- element: The actions default to the module defined as
- <code><font face="courier, monospaced">request</font></code> which is in a default installation to obtain
- the values from request parameters. The name of the parameter
- defaults to table name dot column name.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Other Columns</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Apart from the fact that the auto increment columns are only
- supported for key columns, everything said above applies to value
- columns as well.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Operation Mode Types</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Basically, two different mode types exist:
- <code><font face="courier, monospaced">autoincrement</font></code> which is used whenever data shall be
- inserted into a table and this particular key column has the
- auto increment attribute set and <code><font face="courier, monospaced">others</font></code> for all other
- requirements.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- In addition, a table-set can specify different mode types to use
- instead of the predefined type names. Through this, and the fact
- that every mode can specify a different input module, it is easy to
- use different input modules for different tasks and forms.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- One special mode type name exists that matches all requested ones:
- <code><font face="courier, monospaced">all</font></code> This makes it easier to configure only some
- columns differently for each table-set.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">How to obtain Values</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- As said above, these actions default to reading from request
- parameters with a default parameter name. By specifying
- <code><font face="courier, monospaced">mode</font></code> elements, this can be overridden. Any component
- that implements the <code><font face="courier, monospaced">InputModule</font></code> interface can be used
- to obtain values. How to make such modules known to Apache Cocoon
- is described <a href="../concepts/modules.html">elsewhere</a>.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Beside using different input modules, their parameters can be set
- in place, for example to override parameter names, configure a
- random generator or a message digest algorithm.
- </font>
-</p>
-
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-
- <table name="user_groups">
- <keys>
- <key name="uid" type="int">
- <mode name="request" parameter="user_groups.uid" type="request"/>
- <mode name="attribute" parameter="org.apache.cocoon.components.modules.output.OutputModule:user.uid[0]" type="attrib"/>
- </key>
- <key name="gid" type="int" set="master">
- <mode name="request" parameter="user_groups.gid" type="all"/>
- </key>
- </keys>
- </table>
-
- </pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The above example shows just that: the <code><font face="courier, monospaced">parameter</font></code>
- attribute is not read by the database action itself but the
- complete <code><font face="courier, monospaced">mode</font></code> configuration object is passed to the
- input module. Both the request attribute and the request parameter
- input modules understand this parameter attribute which takes
- precedence over the default one.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Another feature when obtaining values is tied to the
- <code><font face="courier, monospaced">type</font></code> attribute: Different modes can be used in
- different situations. The basic setup uses two different mode
- types: <code><font face="courier, monospaced">autoincrement</font></code> when inserting in key columns
- that have an indicator that they are indeed auto increment columns
- and <code><font face="courier, monospaced">others</font></code> for insert operations on all other columns
- and all other operations on all columns.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Table-sets can override the default names for these two mode type
- name categories with arbitrary names except the special name
- <code><font face="courier, monospaced">all</font></code>. A mode that carries the type name "all" is used
- with all requested type names. Lookup obeys first match principle
- so that all modes are tested from top to bottom and the first that
- matches is used.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">How to store Values e.g. in your Session</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- All modular database action can be configured to use any component
- that implements the <code><font face="courier, monospaced">OutputModule</font></code> interface to store
- values. The output module is chosen on declaring the action in the
- sitemap or dynamically with a sitemap parameter. If no output
- module is specified, the default it to use the request attribute
- module.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- The interface does not allow to pass configuration information to
- the output module. This has to be done when the module is declared
- e.g. in cocoon.xconf.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Inserting Multiple Rows - Sets</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Once common task is to work on more than one row. If the rows are
- in different tables, this is catered for by table-sets. Operating
- on multiple rows of one table requires to mark columns that should
- vary and among those one, that determines the number of rows to
- work on.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- This is done with sets. All columns that cary a <code><font face="courier, monospaced">set</font></code>
- attribute can vary, those, that don't, are kept fixed during the
- operation. The column that is used to determine the number of rows
- is required to have a value of <code><font face="courier, monospaced">master</font></code> while all others
- need to have a value of <code><font face="courier, monospaced">slave</font></code> for the set
- attribute. There may be only one master in a set.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Sets can be tagged either on column or on mode level but not both
- for a single column.
- </font>
-</p>
-
-
-<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Select Your Tables - Table-Sets</font>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Tables that should be used during an operation can be grouped
- together with a table-set. A table-set references tables by their
- name or their alias.
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- In addition, a table-set can override the mode type names for the
- two categories "autoincrement" and "others".
- </font>
-</p>
-
-<p>
-<font color="black" face="verdana,helvetica,sanserif">
- Operations spanning multiple tables in a table-set are done in a
- single transaction. Thus, if one fails, the other is rolled back.
- </font>
-</p>
-
-<div align="center">
-<table border="0" cellpadding="0" cellspacing="4">
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
-<pre>
-
-
- <table name="groups">
- <keys>
- <key name="gid" type="int" autoincrement="true">
- <mode name="auto" type="autoincr"/>
- </key>
- </keys>
- <values>
- <value name="gname" type="string"/>
- </values>
- </table>
-
- <table-set name="user">
- <table name="user"/>
- </table-set>
-
- <table-set name="groups">
- <table name="groups"/>
- </table-set>
-
- <table-set name="user+groups">
- <table name="user"/>
- <table name="user_groups" others-mode="attrib"/>
- </table-set>
-
- <table-set name="user_groups">
- <table name="user_groups" others-mode="request"/>
- </table-set>
-
-</root>
-
- </pre>
-</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-<tr>
-<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
-</tr>
-</table>
-</div>
-
-
-
-
-
-</td>
-</tr>
-</table>
-</td>
-</tr>
-</table>
-<table width="100%" cellspacing="0" cellpadding="0" border="0">
-<tr>
-<td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
-</tr>
-<tr>
-<td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
-</tr>
-</table>
-</body>
-</html>
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>Database Actions</title>
+<STYLE type="text/css">
+a.menu {
+ color: #FFFFFF;
+ text-align:left;
+ font-size:12px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ font-weight:plain;
+ text-decoration:none;
+ padding-left: 14px
+}
+
+A.menu:hover {
+ color: #FFCC00
+}
+
+
+.menutitle {
+ color: #000000;
+ text-align:left;
+ font-size:10px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ font-weight:bold;
+ padding-left: 8px
+}
+.menuselected {
+ color: #FFCC00;
+ text-align:left;
+ font-size:12px;
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ font-weight:bold;
+ padding-left: 14px
+}
+</STYLE>
+</head>
+<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
+<table border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr>
+<td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
+</tr>
+<tr>
+<td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Database Actions</font></td>
+</tr>
+<tr>
+<td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
+<table width="288" cellspacing="0" cellpadding="0" border="0">
+<tr>
+<td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
+</tr>
+</table>
+</td>
+</tr>
+</table>
+<table width="100%" cellspacing="0" cellpadding="0" border="0">
+<tr width="100%">
+<td align="left" valign="top" width="120">
+<table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
+<tr>
+<td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
+</td>
+</tr>
+<tr>
+<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
+</tr>
+<tr>
+<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">User Documentation</a></td>
+</tr>
+<tr>
+<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
+<span class="menutitle">Actions</span></td>
+</tr>
+<tr>
+<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="actions.html">Overview</a></td>
+</tr>
+<tr>
+<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Database</span></td>
+</tr>
+<tr>
+<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
+<span class="menutitle">Default</span></td>
+</tr>
+<tr>
+<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
+<span class="menutitle">Core</span></td>
+</tr>
+<tr>
+<td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
+<span class="menutitle">Optional</span></td>
+</tr>
+<tr>
+<td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session-action.html">Session Action</a></td>
+</tr>
+<tr>
+<td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
+</td>
+</tr>
+</table>
+</td><td>
+<table cellspacing="15" cellpadding="0" border="0">
+<tr>
+<td>
+
+
+
+
+ <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
+<hr style="color: #0086b2" size="1">
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Two different sets of actions exist, that deal with (object) relational
+ database access through JDBC. The original database actions provide a
+ relatively simple interface to store, modify, delete and retrieve data.
+ They are oriented towards usage of request parameters for input and
+ request attributes together with sitemap variables for output and do
+ not support auto increment column types. In addition, the description of
+ the database structure is split over several files since these actions
+ attempt to use all tables in a provided description.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The modular database actions provide similar functionality. In contrast
+ to the original actions they allow to store the database meta data in a
+ single file and to switch input and output flexible through the use of
+ modules. Even for auto increment columns specific modules exist that
+ cover a wide range of database management systems.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ For an overview of column types supported by the modular database
+ actions, see javadocs for JDBCTypeConversions. The types supported by
+ the original actions are documented in AbstractDatabaseAction.
+ </font>
+</p>
+
+
+
+<font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Original Database Actions</font>
+<hr style="color: #0086b2" size="1">
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The original database actions have evolved quite a bit and at different
+ speeds. The add action is certainly the most complete one, providing
+ support for multiple tables and rows. However, the interface has become
+ a bit inconsistent.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ If an error occurs, the original database actions will throw an
+ exception.
+ </font>
+</p>
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Describing the Structure of your DB - descriptor.xml</b></font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The key to database actions is a file that describes database meta
+ data in XML. The original actions will ignore all but the first table
+ and act only on one row. Only the add action will try to access all
+ tables that are contained in this description. As a consequence, each
+ HTML form needs to have a corresponding descriptor file if different
+ tables are affected.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The file name has no meaning and does not need to be
+ <code><font face="courier, monospaced">descriptor.xml</font></code> - it can even be a Cocoon pipeline. The
+ name of the root element in a descriptor file is ignored. Only
+ <code><font face="courier, monospaced">table</font></code> elements nested on first level inside the root
+ element are parsed by the actions. All unknown elements or attributes
+ are ignored.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ For each table a <code><font face="courier, monospaced">table</font></code> element needs to be present.
+ </font>
+</p>
+
+<div align="center">
+<table border="0" cellpadding="0" cellspacing="4">
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
+<pre>
+
+<?xml version="1.0"?>
+
+<employee>
+ <connection>personnel</connection>
+ <table name="employee">
+ <keys>
+ <key param="employee" dbcol="id" type="int" mode="manual"/>
+ </keys>
+ <values>
+ <value param="name" dbcol="name" type="string"/>
+ <value param="department" dbcol="department_id" type="int"/>
+ </values>
+ </table>
+</employee>
+
+ </pre>
+</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+</table>
+</div>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Describes a single table named "employee". In addition a database
+ connection is specified. See <a href="../../developing/datasources.html">here</a> for more
+ information on database connections.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Key Columns</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Tables may or may not have key columns. A key column is a column
+ that is part of the primary key. Actually, candidate keys should do
+ as well.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ All key columns are contained in a <code><font face="courier, monospaced">keys</font></code> child element
+ of the <code><font face="courier, monospaced">table</font></code> element. Each column has a
+ <code><font face="courier, monospaced">key</font></code> element to define its properties. The
+ <code><font face="courier, monospaced">dbcol</font></code> attribute holds the column name,
+ <code><font face="courier, monospaced">type</font></code> is the JDBC type name for this column (have a
+ look at AbstactDatabaseAction source for valid type names),
+ <code><font face="courier, monospaced">param</font></code> specifies the name of the request parameter to
+ use, and <code><font face="courier, monospaced">mode</font></code> sets how the value for this column is
+ obtained on adding a row.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Through the mode attribute the behaviour of the add action can be
+ changed.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Default mode is "automatic" and to let the database create the key
+ value by setting this value to <code><font face="courier, monospaced">null</font></code>. The created value
+ can not be read back from the database and will not be available as
+ request attribute or sitemap variable.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ A mode of "manual" will query the database for the maximum current
+ value, add 1 to it and use that for a value.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ A mode of "form" will use the corresponding request parameter.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ A mode of "request-attribute" will use the corresponding request
+ attribute. The name specified in the <code><font face="courier, monospaced">param</font></code> attribute
+ will be automatically prefixed with the class name.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Key values will be propagated to sitemap variables and - prefixed
+ with the class name - request attributes.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Other Columns</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ All other columns are contained in a <code><font face="courier, monospaced">values</font></code> child
+ element of the <code><font face="courier, monospaced">table</font></code> element. Each column has a
+ <code><font face="courier, monospaced">value</font></code> element to define its properties. Properties are
+ similar to those for key columns. A <code><font face="courier, monospaced">mode</font></code> attribute
+ does not exist for value columns. Instead, request parameters and
+ request attributes are tried in this order for the specified
+ parameter.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Request attribute names are <i>not</i> prefixed with the class
+ name. Thus, to insert the value of a key column of the previous row
+ or previous table into a value column, it needs to be named
+ <code><font face="courier, monospaced">org.apache.cocoon.acting.AbstractDatabaseAction:key:table:dbcol</font></code>.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Value columns are propagated to request attributes with class name
+ prefix. They are not available for the sitemap.
+ </font>
+</p>
+
+
+
+
+<font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Modular Database Actions</font>
+<hr style="color: #0086b2" size="1">
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The modular database actions were mainly created to make auto increment
+ columns available, handle input and output flexibly, and have a
+ consistent interface. A successful action will return the number of
+ rows affected in a sitemap parameter named <code><font face="courier, monospaced">row-count</font></code>. The
+ added features required to change the descriptor file format in
+ incompatible ways.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ It can be configured if an exception will be thrown when an error
+ occurs.
+ </font>
+</p>
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Describing the Structure of your DB - descriptor.xml</b></font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Like the original actions, the modular actions need meta data in an
+ XML file. However, that file may contain any number of tables, not
+ just the ones needed for a single request. The tables actually used
+ are referenced through a <code><font face="courier, monospaced">table-set</font></code>. Unknown elements and
+ attributes are ignored. This way a descriptor file can be shared with
+ other actions like the form validator.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ For the flexible input and output handling, the modular database
+ actions rely on <a href="../concepts/modules.html">modules</a>.
+ Have a look at those before proceeding.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The following is a snippet from a descriptor file.
+ </font>
+</p>
+
+<div align="center">
+<table border="0" cellpadding="0" cellspacing="4">
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
+<pre>
+
+<root>
+ <connection>personnel</connection>
+ <table name="user" alias="user">
+ <keys>
+ <key name="uid" type="int" autoincrement="true">
+ <mode name="auto" type="autoincr"/>
+ </key>
+ </keys>
+ <values>
+ <value name="name" type="string"></value>
+ <value name="firstname" type="string"></value>
+ <value name="uname" type="string"></value>
+ </values>
+ </table>
+
+ </pre>
+</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+</table>
+</div>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The <code><font face="courier, monospaced">table</font></code> element has an additional attribute
+ <code><font face="courier, monospaced">alias</font></code> which is an alternative name to reference
+ the table from a table set. The descriptor file is searched
+ top down for tables whose <code><font face="courier, monospaced">name</font></code> or
+ <code><font face="courier, monospaced">alias</font></code> match. The <code><font face="courier, monospaced">alias</font></code>n attribute
+ is useful if a complex join expression is used as table
+ name. In such a case modifications like update, insert,
+ delete will likely fail.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Another application of aliases if different numbers of columns should
+ be affected by an operation. or if a table contains several candidate
+ keys that are used alternatively. This way, different views to a
+ table can be created.
+ </font>
+</p>
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Key Columns</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The descriptor file resembles the one for the original actions. One
+ major difference is the absence of <code><font face="courier, monospaced">dbcol</font></code> and
+ <code><font face="courier, monospaced">param</font></code> attributes. Instead there is a <code><font face="courier, monospaced">name</font></code>
+ attribute which corresponds to the <code><font face="courier, monospaced">dbcol</font></code> attribute and
+ specifies the database column name.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ If a column is an auto increment column, the similar named attribute
+ indicates this. Auto increment columns will be handled differently
+ on insert operations.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Instead of specifying a parameter name, the actions support to use
+ different input modules for each operation through the nested
+ <code><font face="courier, monospaced">mode</font></code> elements. This is described in more detail below.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Note here though, that not every column needs a <code><font face="courier, monospaced">mode</font></code>
+ element: The actions default to the module defined as
+ <code><font face="courier, monospaced">request</font></code> which is in a default installation to obtain
+ the values from request parameters. The name of the parameter
+ defaults to table name dot column name.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Other Columns</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Apart from the fact that the auto increment columns are only
+ supported for key columns, everything said above applies to value
+ columns as well.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Operation Mode Types</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Basically, two different mode types exist:
+ <code><font face="courier, monospaced">autoincrement</font></code> which is used whenever data shall be
+ inserted into a table and this particular key column has the
+ auto increment attribute set and <code><font face="courier, monospaced">others</font></code> for all other
+ requirements.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ In addition, a table-set can specify different mode types to use
+ instead of the predefined type names. Through this, and the fact
+ that every mode can specify a different input module, it is easy to
+ use different input modules for different tasks and forms.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ One special mode type name exists that matches all requested ones:
+ <code><font face="courier, monospaced">all</font></code> This makes it easier to configure only some
+ columns differently for each table-set.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">How to obtain Values</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ As said above, these actions default to reading from request
+ parameters with a default parameter name. By specifying
+ <code><font face="courier, monospaced">mode</font></code> elements, this can be overridden. Any component
+ that implements the <code><font face="courier, monospaced">InputModule</font></code> interface can be used
+ to obtain values. How to make such modules known to Apache Cocoon
+ is described <a href="../concepts/modules.html">elsewhere</a>.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Beside using different input modules, their parameters can be set
+ in place, for example to override parameter names, configure a
+ random generator or a message digest algorithm.
+ </font>
+</p>
+
+
+<div align="center">
+<table border="0" cellpadding="0" cellspacing="4">
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
+<pre>
+
+ <table name="user_groups">
+ <keys>
+ <key name="uid" type="int">
+ <mode name="request" parameter="user_groups.uid" type="request"/>
+ <mode name="attribute" parameter="org.apache.cocoon.components.modules.output.OutputModule:user.uid[0]" type="attrib"/>
+ </key>
+ <key name="gid" type="int" set="master">
+ <mode name="request" parameter="user_groups.gid" type="all"/>
+ </key>
+ </keys>
+ </table>
+
+ </pre>
+</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+</table>
+</div>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The above example shows just that: the <code><font face="courier, monospaced">parameter</font></code>
+ attribute is not read by the database action itself but the
+ complete <code><font face="courier, monospaced">mode</font></code> configuration object is passed to the
+ input module. Both the request attribute and the request parameter
+ input modules understand this parameter attribute which takes
+ precedence over the default one.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Another feature when obtaining values is tied to the
+ <code><font face="courier, monospaced">type</font></code> attribute: Different modes can be used in
+ different situations. The basic setup uses two different mode
+ types: <code><font face="courier, monospaced">autoincrement</font></code> when inserting in key columns
+ that have an indicator that they are indeed auto increment columns
+ and <code><font face="courier, monospaced">others</font></code> for insert operations on all other columns
+ and all other operations on all columns.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Table-sets can override the default names for these two mode type
+ name categories with arbitrary names except the special name
+ <code><font face="courier, monospaced">all</font></code>. A mode that carries the type name "all" is used
+ with all requested type names. Lookup obeys first match principle
+ so that all modes are tested from top to bottom and the first that
+ matches is used.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">How to store Values e.g. in your Session</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ All modular database action can be configured to use any component
+ that implements the <code><font face="courier, monospaced">OutputModule</font></code> interface to store
+ values. The output module is chosen on declaring the action in the
+ sitemap or dynamically with a sitemap parameter. If no output
+ module is specified, the default it to use the request attribute
+ module.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ The interface does not allow to pass configuration information to
+ the output module. This has to be done when the module is declared
+ e.g. in cocoon.xconf.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Inserting Multiple Rows - Sets</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Once common task is to work on more than one row. If the rows are
+ in different tables, this is catered for by table-sets. Operating
+ on multiple rows of one table requires to mark columns that should
+ vary and among those one, that determines the number of rows to
+ work on.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ This is done with sets. All columns that cary a <code><font face="courier, monospaced">set</font></code>
+ attribute can vary, those, that don't, are kept fixed during the
+ operation. The column that is used to determine the number of rows
+ is required to have a value of <code><font face="courier, monospaced">master</font></code> while all others
+ need to have a value of <code><font face="courier, monospaced">slave</font></code> for the set
+ attribute. There may be only one master in a set.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Sets can be tagged either on column or on mode level but not both
+ for a single column.
+ </font>
+</p>
+
+
+<font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Select Your Tables - Table-Sets</font>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Tables that should be used during an operation can be grouped
+ together with a table-set. A table-set references tables by their
+ name or their alias.
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ In addition, a table-set can override the mode type names for the
+ two categories "autoincrement" and "others".
+ </font>
+</p>
+
+<p>
+<font color="black" face="verdana,helvetica,sanserif">
+ Operations spanning multiple tables in a table-set are done in a
+ single transaction. Thus, if one fails, the other is rolled back.
+ </font>
+</p>
+
+<div align="center">
+<table border="0" cellpadding="0" cellspacing="4">
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
+<pre>
+
+
+ <table name="groups">
+ <keys>
+ <key name="gid" type="int" autoincrement="true">
+ <mode name="auto" type="autoincr"/>
+ </key>
+ </keys>
+ <values>
+ <value name="gname" type="string"/>
+ </values>
+ </table>
+
+ <table-set name="user">
+ <table name="user"/>
+ </table-set>
+
+ <table-set name="groups">
+ <table name="groups"/>
+ </table-set>
+
+ <table-set name="user+groups">
+ <table name="user"/>
+ <table name="user_groups" others-mode="attrib"/>
+ </table-set>
+
+ <table-set name="user_groups">
+ <table name="user_groups" others-mode="request"/>
+ </table-set>
+
+</root>
+
+ </pre>
+</td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+<tr>
+<td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
+</tr>
+</table>
+</div>
+
+
+
+
+
+</td>
+</tr>
+</table>
+</td>
+</tr>
+</table>
+<table width="100%" cellspacing="0" cellpadding="0" border="0">
+<tr>
+<td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
+</tr>
+<tr>
+<td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright © 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
+</tr>
+</table>
+</body>
+</html>