haul 02/04/28 11:11:12
Modified: src/documentation/xdocs/userdocs/concepts book.xml
Added: src/documentation/xdocs/userdocs/concepts modules.xml
databases.xml
Log:
docs for database operations and modules
Revision Changes Path
1.4 +2 -0 xml-cocoon2/src/documentation/xdocs/userdocs/concepts/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/concepts/book.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- book.xml 14 Mar 2002 21:43:00 -0000 1.3
+++ book.xml 28 Apr 2002 18:11:12 -0000 1.4
@@ -22,6 +22,8 @@
<menu-item label="Persistence" href="persistence.html"/>
<menu-item label="StoreJanitor" href="storejanitor.html"/>
<menu-item label="XMLSearching" href="xmlsearching.html"/>
+ <menu-item label="Databases" href="databases.html"/>
+ <menu-item label="Modules" href="modules.html"/>
</menu>
</book>
1.1
xml-cocoon2/src/documentation/xdocs/userdocs/concepts/modules.xml
Index: modules.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
<header>
<title>Modules</title>
<authors>
<person name="Christian Haul" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
Many sitemap components serve a purpose regardless how the input is
obtained. Still, to provide a wide range of components to quickly get
you up to speed, variants for different inputs exist. Modules allow to
create generic components and plug-in input or output later.
</p>
<p>
This document will explain how modules work and how to make use of
them. If you plan on writing your own modules, it is highly recommended
to read <fork
href="http://jakarta.apache.org/avalon/developing/index.html";>
Developing With Apache Avalon</fork>. It is a very good description
of the underlying rationale and principles.
</p>
<note>
To use modules, Apache Cocoon needs to have been build to include
scratchpad components.
</note>
</s1>
<s1 title="Types of Modules">
<p>
Currently, three different types of modules exist: Input modules
provide means to enumerate parameters and to retrieve them, output
modules allow storing of data and exhibit transaction like semantics,
database modules encapsulate different mechanisms for auto increment
columns of various database management systems. Please refer to the
javadoc documentation of these interfaces.
</p>
<p>
Input modules are modelled after request parameters. The main
difference is, that every method takes two additional arguments, the
request object and a configuration object. The configuration object is
used to allow arbitrarily complex instructions for the input module.
Apart from that, input modules are more or less a drop-in replacement.
</p>
<p>
Output modules are again very similar to using request
attributes. Basically, they provide a method to set an attribute to a
value. Again, a request and a configuration object is the only change
to request attributes. A fundamental difference is, however, that
output modules should exhibit transactional behaviour. Thus setting an
attributes implicitly starts a transaction that must be ended by
calling rollback or commit. Only if the transaction is completed by
calling commit, the values set should be visible. This is needed
e.g. by the database actions.
</p>
<p>
Database modules, actually named AutoIncrementModule, contains
configuration information how to retrieve a value for an auto increment
column. It is possible to obtain the value before inserting a row,
while inserting as part of the SQL or after successful insert. If the
value is obtained before inserting, it can be generated
externally. Currently, supported database management systems include
HSQL, Informix, MySQL, and querying the database for the current max
value.
</p>
</s1>
<s1 title="Using modules">
<p>
Using any of these modules requires a two step setup process. Step one
has already been done for your for all modules that come with Apache
Cocoon. Exception to this rule are the auto increment modules: only the
HSQL module is already setup.
</p>
<s2 title="Step 1: Making a new module know to Apache Cocoon">
<p>
Like other core components of Apache Cocoon, modules are declared in
<code>cocoon.xconf</code>.
</p>
<source>
<![CDATA[
<input-modules>
<component-instance name="request"
class="org.apache.cocoon.components.modules.input.RequestParameterModule"/>
<component-instance name="attribute"
class="org.apache.cocoon.components.modules.input.RequestAttributeModule"/>
<component-instance name="URI"
class="org.apache.cocoon.components.modules.input.RequestURIModule"/>
<component-instance name="header"
class="org.apache.cocoon.components.modules.input.HeaderAttributeModule"/>
<component-instance name="session"
class="org.apache.cocoon.components.modules.input.SessionAttributeModule"/>
</input-modules>
<output-modules>
<component-instance name="attribute"
class="org.apache.cocoon.components.modules.output.RequestAttributeOutputModule"/>
<component-instance name="session"
class="org.apache.cocoon.components.modules.output.SessionAttributeOutputModule"/>
</output-modules>
<autoincrement-modules>
<component-instance name="auto"
class="org.apache.cocoon.components.modules.database.HsqlIdentityAutoIncrementModule"/>
<!--
<component-instance name="auto"
class="org.apache.cocoon.components.modules.database.ManualAutoIncrementModule"/>
<component-instance name="auto"
class="org.apache.cocoon.components.modules.database.IfxSerialAutoIncrementModule"/>
<component-instance name="auto"
class="org.apache.cocoon.components.modules.database.MysqlAutoIncrementModule"/>
-->
</autoincrement-modules>
]]>
</source>
<p>
The above snippet declares a number of modules. After this, the
modules are accessible through the given name. Thus, when an
<code>input-module</code> is expected, it is sufficient to give the
name of a module, like <code>header</code>.
</p>
<p>
For the auto increment modules only one is declared as the name
<code>"auto"</code> has special meaning to the modular database
actions. If more than one is needed at the same time, the
configuration of the database actions needs to explicitly specify
which one to use.
</p>
</s2>
<s2 title="Step 2: Have sitemap component use a module">
<p>
This depends on the component that is to be used. As an example the
<code>CachingWildcardMatcher</code> requires to set the
<code>input-module</code> on declaration.
</p>
<source>
<![CDATA[
<map:matchers default="wildcard">
<map:matcher name="cached-uri"
src="org.apache.cocoon.matching.modular.CachingWildcardMatcher">
<input-module name="URI"/>
</map:matcher>
</map:matchers>
]]>
</source>
<p>
By replacing the input module name with any of the other declared
input modules, this matcher can be used to match e.g. on session
attributes or request headers.
</p>
</s2>
</s1>
</body>
</document>
1.1
xml-cocoon2/src/documentation/xdocs/userdocs/concepts/databases.xml
Index: databases.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 Access</title>
<authors>
<person name="Christian Haul" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
Publishing dynamic content or creating web-applications at
some point often involves database access. Apache Cocoon
offers a number of different facilities to access databases,
(object) relational and XML. This document aims to give an
overview over the different choices to access (object)
relational databases.
</p>
<p>
This document will not explain how to setup database
connectivity with Apache Cocoon. For this, see <link
href="../../developing/datasources.html">here.</link>
</p>
<p>
Basically, there are three different approaches available:
<link href="actions.html">Actions,</link> <link
href="../xsp/logicsheet-concepts.html">logicsheets,</link>
and <link href="sitemap.html">transformers.</link> Each has
its merits and difficulties.
</p>
</s1>
<s1 title="Actions">
<p>
<link href="actions.html">Actions</link> are code that is executed
during pipeline setup and its outcome can change how the pipeline is
assembled. This way a pipeline can for example contain an alternative
page to display when a database operation failed.
</p>
<p>
Actions are especially great to insert, change, or delete data. By
using the pipeline switching feature of actions, pages can be simpler
as they are only concerned with one view - either successful operation
or failure.
</p>
<p>
Even for data that is not user-provided, actions can be useful.
Tracking information can be stored in a database from a central
location without the need to modify every page.
</p>
<p>
Database actions allow also to read data from a database. This is
useful if the pipeline assembling depends on this data or to setup an
environment for processing on a XSP.
</p>
<p>
A big advantage of these actions is, that once the database meta data
is captured into a descriptor file in XML, using any of these actions
is just a matter of placing it in the pipeline, no programming is
required, not even writing SQL queries.
</p>
<p>
A detailed description can be found <link
href="../actions/database-actions.html">here</link>.
</p>
</s1>
<s1 title="ESQL Logicsheet">
<p>
Usage of logicsheets is limited to XSPs, ESQL is currently available
for JAVA XSPs. In addition, the interface is largely modelled after
JDBC, and it is advantageous to be familiar with it.
</p>
<p>
ESQL is great to read data from a database while it is less attractive
to react to operation failures because that makes the XSP complex and
less easy to understand and maintain.
</p>
<p>
Complex layouts of the data read are easy to achieve. ESQL allows
arbitrary nesting of queries and connections, provides support for
stored procedures and complex data types. For generating reports that
can be used with other XML-aware software or formated with XSL or CSS2,
ESQL provides means to create a structured representation of the
database data with just one tag. XML data can be retrieved from the
database and included in the output, ESQL supports skipping part of the
resultset and limiting the result with some supported database
management systems. With the full power of JAVA available on the XSP,
any processing of the data is possible.
</p>
<p>
A detailed description can be found <link
href="../xsp/esql.html">here</link>.
</p>
</s1>
<s1 title="SQL Transformer">
<p>
As a transformer, this approach can be combined with any kind
of page. This results in slightly cleaner pages as some of the
setup ESQL requires is not needed.
</p>
<p>
On the other hand it is more or less impossible to react to operation
failures since the pipeline is already assembled and logic is not
available inside transformers unless a custom transformer is written.
This makes the transformer approach best for retrieving data. Creating
an XML representation of the query result is even simpler than with
using the ESQL logicsheet. The transformer supports stored procedures.
No programming is required apart from writing SQL.
</p>
<p>
A detailed description can be found <link
href="../transformers/sql-transformer.html">here</link>.
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
