Author: tfischer
Date: Mon Jun 4 03:03:17 2012
New Revision: 1345817
URL: http://svn.apache.org/viewvc?rev=1345817&view=rev
Log:
Improved the generator documentation
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml?rev=1345817&r1=1345816&r2=1345817&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
(original)
+++
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/concepts.xml
Mon Jun 4 03:03:17 2012
@@ -26,8 +26,7 @@
<body>
<section name="Introduction">
- This document introduces the main concepts of the Torque generation
- framework.
+ This document introduces the main concepts of the Torque generator.
The following concepts are explained:
<ul>
<li>
@@ -58,6 +57,9 @@
<a href="#Namespaces">Namespaces</a>
</li>
<li>
+ <a href="#Configuration">Configuration</a>
+ </li>
+ <li>
<a href="#Overriding">Overriding</a>
</li>
</ul>
@@ -263,10 +265,35 @@
</p>
</section>
+ <section name="Configuration">
+ <p>
+ The configuration of the Torque generator tells the
+ <a href="#Controller">Controller</a> which <a href="#Options">option</a>
+ files are read, which output files are produced from which
+ <a href="#Outlets">Outlets</a> and <a href="#Sources">Sources</a>,
+ which <a href="#SkipDeciders">SkipDeciders</a> and which
+ <a href="#Transformers">Transformers</a> should be used, and which
+ <a href="#Outlets">Outlets</a> are connected to which
+ <a href="#Mergepoints">Mergepoints</a>.
+ The configuration of the Torque generator is described in detail
+ in the <a href="configuration.html">configuration section</a>
+ of the Torque generation documentation.
+ </p>
+ </section>
+
<section name="Overriding">
<p>
- TODO The Torque generator offers overriding via a parent-child
mechanism.
+ The Torque generator offers overriding via a parent-child mechanism.
+ A generator configuration can inherit from another generator
+ configuration; and settings can be overridden or added.
+ This can be used to customize the generation output.
+ A common way to change the output is to add or change
+ <a href="#Outlets">Outlets</a> which are used by the generation
mechanism.
+ E.g. one can replace a template in all places by overriding
+ an <a href="#Outlets">Outlet</a> definition in a child configuration,
+ or one can disable the use of an outlet in a place by overriding a
+ <a href="#Mergepoints">Mergepoint</a> definition.
</p>
</section>
</body>
-</document>
\ No newline at end of file
+</document>
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml?rev=1345817&r1=1345816&r2=1345817&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
(original)
+++
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/configuration.xml
Mon Jun 4 03:03:17 2012
@@ -258,6 +258,37 @@
</outlet>
</outlets>
]]></source>
+ <p>
+ A more exotic case is the definition of mergepoints outside
+ an outlet tag. This is useful when overriding a mergepoint definition
+ in a child project. The mergepoint can be accessed by
+ ${outletName}.${mergepointName}. For example, if we want to override
+ the <i>setter</i> mergepoint in the
+ <i>torque.om.bean.base.getterSetter</i> to use a custom velocity
+ template named <i>setter2.vm</i>, we could use the following
+ configuration in the child project:
+ </p>
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<outlets xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+
xsi:schemaLocation="http://db.apache.org/torque/4.0/generator/configuration
http://db.apache.org/torque/4.0/generator/configuration.xsd";
+ xmlns="http://db.apache.org/torque/4.0/generator/configuration";>
+ <mergepoint name="torque.om.bean.base.getterSetter.setter">
+ <action xsi:type="applyAction" outlet="torque.om.bean.base.setter2"/>
+ </mergepoint>
+
+ <outlet name="torque.om.bean.base.setter2"
+ xsi:type="velocityOutlet"
+ path="bean/base/setter2.vm">
+ </outlet>
+</outlets>
+]]></source>
+ <p>
+ Note that by virtue of the standalone mergepoint definition,
+ we need not override the whole definition for the outlet
+ <i>torque.om.bean.base.getterSetter</i>, but can override a single
+ mergepoint definition.
+ </p>
</subsection>
</section>
</body>
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals.xml
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals.xml?rev=1345817&r1=1345816&r2=1345817&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals.xml
(original)
+++
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals.xml
Mon Jun 4 03:03:17 2012
@@ -26,8 +26,9 @@
<body>
<section name="Internals">
- The documents in this section contains explanations how torque-gf
- works internally. This information is not needed to just use torque-gf.
+ The documents in this section contains explanations how the Torque
generator
+ works internally. This information is not needed to just use the
+ Torque generator.
</section>
</body>
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
URL:
http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml?rev=1345817&r1=1345816&r2=1345817&view=diff
==============================================================================
---
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
(original)
+++
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/generator/reference/internals/outletTypes.xml
Mon Jun 4 03:03:17 2012
@@ -39,13 +39,17 @@
outlet and filenameOutlet elements in the project configuration).
The Torque generator needs to be told which parser it should use for which
outlet type. This is done by registering a outletHandlerFactory
- for each generator type, see
-
<code>OutletTypes.registerOutletHandlerFactory(OutletSaxHandlerFactory)</code>.
+ for each generator type, see the register methods in the
+ <code>org.apache.torque.generator.configuration.OutletTypes</code> class.
The outletTypes instance is accessible via the ConfigurationHandlers
- instance passed from the Configuration object.
+ instance in the Configuration object.
This could in principle be used to plug in new outlet types,
but alas, the configuration object is hidden in the controller instance
- and not accessible from the outside :-(.
+ and not accessible from the outside :-(. However, there is one
+ handler factory registered by default, the
+
<code>org.apache.torque.generator.configuration.outlet.ReflectionOutletSaxHandlerFactory</code>,
+ which can be used to access new outlet types using a naming convention;
+ which suffices to register new outlet types.
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
