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/concepts modules.xml databases.xml book.xml
Date Sun, 28 Apr 2002 18:11:13 GMT
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="haul@apache.org"/>
      </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="haul@apache.org"/>
      </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:     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