cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From h...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/actions database-actions.xml book.xml
Date Sun, 28 Apr 2002 18:14:45 GMT
haul        02/04/28 11:14:45

  Modified:    src/documentation/xdocs/userdocs/actions book.xml
  Added:       src/documentation/xdocs/userdocs/actions
                        database-actions.xml
  Log:
  docs for database operations and modules
  
  Revision  Changes    Path
  1.2       +1 -0      xml-cocoon2/src/documentation/xdocs/userdocs/actions/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/actions/book.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- book.xml	3 Jan 2002 12:31:04 -0000	1.1
  +++ book.xml	28 Apr 2002 18:14:45 -0000	1.2
  @@ -12,6 +12,7 @@
   
     <menu label="Actions">
       <menu-item label="Overview" href="actions.html"/>
  +    <menu-item label="Database" href="database-actions.html"/>
     </menu>
     <menu label="Default">
     </menu>
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/userdocs/actions/database-actions.xml
  
  Index: database-actions.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <document>
  
    <header>
      <title>Database Actions</title>
      <authors>
        <person name="Christian Haul" email="haul@apache.org"/>
      </authors>
    </header>
  
    <body>
  	<s1 title="Introduction">
  	  <p>
  		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.
  	  </p>
  	  <p>
  		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.
  	  </p>
  	</s1>
  
  	<s1 title="Original Database Actions">
  	  <p>
  		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.
  	  </p>
  	  <p>
  		If an error occurs, the original database actions will throw an
  		exception.
  	  </p>
  	  <s2 title="Describing the Structure of your DB - descriptor.xml">
  		<p>
  		  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.
  		</p>
  		<p>
  		  The file name has no meaning and does not need to be
  		  <code>descriptor.xml</code> - it can even be a Cocoon pipeline. The
  		  name of the root element in a descriptor file is ignored. Only
  		  <code>table</code> elements nested on first level inside the root
  		  element are parsed by the actions. All unknown elements or attributes
  		  are ignored.
  		</p>
  		<p>
  		  For each table a <code>table</code> element needs to be present. 
  		</p>
  		<source>
  <![CDATA[
  <?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>
  ]]>	
  		</source>
  		<p>
  		  Describes a single table named "employee". In addition a database
  		  connection is specified. See <link
  			href="../../developing/datasources.html">here</link> for more
  		  information on database connections. 
  		</p>
  
  		<s3 title="Key Columns">
  		  <p>
  			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.
  		  </p>
  		  <p>
  			All key columns are contained in a <code>keys</code> child element
  			of the <code>table</code> element. Each column has a
  			<code>key</code> element to define its properties. The
  			<code>dbcol</code> attribute holds the column name,
  			<code>type</code> is the JDBC type name for this column (have a
  			look at AbstactDatabaseAction source for valid type names),
  			<code>param</code> specifies the name of the request parameter to
  			use, and <code>mode</code> sets how the value for this column is
  			obtained on adding a row.
  		  </p>
  		  <p>
  			Through the mode attribute the behaviour of the add action can be
  			changed.
  		  </p> 
  		  <p>
  			Default mode is "automatic" and to let the database create the key
  			value by setting this value to <code>null</code>. The created value
  			can not be read back from the database and will not be available as
  			request attribute or sitemap variable.
  		  </p>
  		  <p>
  			A mode of "manual" will query the database for the maximum current
  			value, add 1 to it and use that for a value.
  		  </p>
  		  <p>
  			A mode of "form" will use the corresponding request parameter.
  		  </p>
  		  <p>
  			A mode of "request-attribute" will use the corresponding request
  			attribute. The name specified in the <code>param</code> attribute
  			will be automatically prefixed with the class name.
  		  </p>
  		  <p>
  			Key values will be propagated to sitemap variables and - prefixed
  			with the class name - request attributes.
  		  </p>
  		</s3>
  		<s3 title="Other Columns">
  		  <p>
  			All other columns are contained in a <code>values</code> child
  			element of the <code>table</code> element. Each column has a
  			<code>value</code> element to define its properties. Properties are
  			similar to those for key columns. A <code>mode</code> attribute
  			does not exist for value columns. Instead, request parameters and
  			request attributes are tried in this order for the specified
  			parameter. 
  		  </p>
  		  <p>
  			Request attribute names are <em>not</em> 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>org.apache.cocoon.acting.AbstractDatabaseAction:key:table:dbcol</code>.

  		  </p>
  		  <p>
  			Value columns are propagated to request attributes with class name
  			prefix. They are not available for the sitemap.
  		  </p>
  		</s3>
  	  </s2>
  	</s1>
  	<s1 title="Modular Database Actions">
  	  <p>
  		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>row-count</code>. The
  		added features required to change the descriptor file format in
  		incompatible ways.
  	  </p>
  	  <p>
  		It can be configured if an exception will be thrown when an error
  		occurs.
  	  </p>
  	  <s2 title="Describing the Structure of your DB - descriptor.xml">
  		<p>
  		  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>table-set</code>. Unknown elements and
  		  attributes are ignored. This way a descriptor file can be shared with
  		  other actions like the form validator.
  		</p>
  		<p>
  		  For the flexible input and output handling, the modular database
  		  actions rely on <link href="../concepts/modules.html">modules</link>.
  		  Have a look at those before proceeding.
  		</p>
          <p>
            The following is a snippet from a descriptor file. 
          </p>
  		<source>
  <![CDATA[
  <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>
  ]]>
          </source>
          <p>
            The <code>table</code> element has an additional attribute
            <code>alias</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>name</code> or
            <code>alias</code> match. The <code>alias</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.
          </p>
  		<p>
  		  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.
  		</p>
  		<s3 title="Key Columns">
  		  <p>
  			The descriptor file resembles the one for the original actions. One
  			major difference is the absence of <code>dbcol</code> and
  			<code>param</code> attributes. Instead there is a <code>name</code>
  			attribute which corresponds to the <code>dbcol</code> attribute and
  			specifies the database column name.
  		  </p>
  		  <p>
  			If a column is an auto increment column, the similar named attribute
  			indicates this. Auto increment columns will be handled differently
  			on insert operations.
  		  </p>
  		  <p>
  			Instead of specifying a parameter name, the actions support to use
  			different input modules for each operation through the nested
  			<code>mode</code> elements. This is described in more detail below.
  		  </p>
  		  <p>
  			Note here though, that not every column needs a <code>mode</code>
  			element: The actions default to the module defined as
  			<code>request</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.
  		  </p>
  		</s3>
  		<s3 title="Other Columns">
  		  <p>
              Apart from the fact that the auto increment columns are only
  			supported for key columns, everything said above applies to value
  			columns as well.
            </p>
  		</s3>
  		<s3 title="Operation Mode Types">
  		  <p>
  			Basically, two different mode types exist:
  			<code>autoincrement</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>others</code> for all other
  			requirements.
            </p>
            <p>
              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.
            </p>
            <p>
              One special mode type name exists that matches all requested ones:
  			<code>all</code> This makes it easier to configure only some
  			columns differently for each table-set.
            </p>
  		</s3>
  		<s3 title="How to obtain Values">
  		  <p>
  			As said above, these actions default to reading from request
  			parameters with a default parameter name. By specifying
  			<code>mode</code> elements, this can be overridden. Any component
  			that implements the <code>InputModule</code> interface can be used
  			to obtain values. How to make such modules known to Apache Cocoon
  			is described  <link href="../concepts/modules.html">elsewhere</link>. 
  		  </p>
  		  <p>
  			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.
  		  </p>
  
  		  <source>
  <![CDATA[
     <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>
  ]]>
  		  </source>
  		  <p>
  			The above example shows just that: the <code>parameter</code>
  			attribute is not read by the database action itself but the
  			complete <code>mode</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.
  		  </p>
  		  <p>
  			Another feature when obtaining values is tied to the
  			<code>type</code> attribute: Different modes can be used in
  			different situations. The basic setup uses two different mode
  			types: <code>autoincrement</code> when inserting in key columns
  			that have an indicator that they are indeed auto increment columns
  			and <code>others</code> for insert operations on all other columns
  			and all other operations on all columns.
  		  </p>
  		  <p>
  			Table-sets can override the default names for these two mode type
  			name categories with arbitrary names except the special name
  			<code>all</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.
  		  </p>
  		</s3>
  		<s3 title="How to store Values e.g. in your Session">
  		  <p>
  			All modular database action can be configured to use any component
  			that implements the <code>OutputModule</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.
  		  </p>
  		  <p>
  			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.
  		  </p>
  		</s3>
  		<s3 title="Inserting Multiple Rows - Sets">
  		  <p>
  			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.
  		  </p>
  		  <p>
  			This is done with sets. All columns that cary a <code>set</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>master</code> while all others
  			need to have a value of <code>slave</code> for the set
  			attribute. There may be only one master in a set.
  		  </p>
  		  <p>
  			Sets can be tagged either on column or on mode level but not both
  			for a single column.
  		  </p>
  		</s3>
  		<s3 title="Select Your Tables - Table-Sets">
  		  <p>
  			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.
  		  </p>
  		  <p>
  			In addition, a table-set can override the mode type names for the
  			two categories "autoincrement" and "others".
  		  </p>
  		  <p>
  			Operations spanning multiple tables in a table-set are done in a
  			single transaction. Thus, if one fails, the other is rolled back.
  		  </p>
  		  <source>
  <![CDATA[
  
     <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>
  ]]>
  		  </source>
  		</s3>
  	  </s2>
  	</s1>
    </body>
  </document>
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message