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]
