db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r1460187 - in /db/torque/torque4/trunk/torque-site/src/site: site.xml xdoc/documentation/codegen-reference/logging-debugging.xml xdoc/documentation/codegen-reference/logging.xml
Date Sat, 23 Mar 2013 16:22:39 GMT
Author: tfischer
Date: Sat Mar 23 16:22:38 2013
New Revision: 1460187

URL: http://svn.apache.org/r1460187
Log:
improve logging documentation; add debugging documentation

Added:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml
      - copied, changed from r1456690, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml
Removed:
    db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml
Modified:
    db/torque/torque4/trunk/torque-site/src/site/site.xml

Modified: db/torque/torque4/trunk/torque-site/src/site/site.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/site.xml?rev=1460187&r1=1460186&r2=1460187&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/site.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/site.xml Sat Mar 23 16:22:38 2013
@@ -97,7 +97,7 @@
         <item name="Configuration"       href="/documentation/codegen-reference/configuration.html"/>
         <item name="Extending"           href="/documentation/codegen-reference/extending.html"/>
         <item name="Target Modes"        href="/documentation/codegen-reference/existing-target-modes.html"/>
-        <item name="Logging"             href="/documentation/codegen-reference/logging.html"/>
+        <item name="Logging and Debugging" href="/documentation/codegen-reference/logging-debugging.html"/>
         <item name="Generator Internals" href="/documentation/codegen-reference/generator-internals/index.html"
collapse="true">
           <item name="Outlet Types"      href="/documentation/codegen-reference/generator-internals/outletTypes.html"/>
         </item>

Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml
(from r1456690, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml)
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml&r1=1456690&r2=1460187&rev=1460187&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml
(original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml
Sat Mar 23 16:22:38 2013
@@ -21,15 +21,97 @@
 <document>
 
  <properties>
-  <title>Logging</title>
+  <title>Logging and Debugging</title>
  </properties>
 
  <body>
-  <section name="Logging in the Torque generator">
+  
+  <section name="Logging Output of the Torque generator">
     <p>
-     The Torque generator uses logging to visualize the work it is doing
-     at the moment. It commons-logging as logging abstraction, so in principle,
-     it is logging-framework agnostic.
+      The Torque generator uses logging to visualize the work it does.
+      The log information is written to the console, plus it is written
+      to the file target/torque-gen/log/torque-gen.log. The default log
+      level is INFO. The log level can be changed in two places:
+    </p>
+    <ul>
+      <li>
+        The templates can define a default log level 
+        using the loglevel attribute of the control element 
+        in the control.xml configuration file.
+      </li>
+      <li>
+        When executing the templates, another log level can be passed in,
+        overriding the log level defined in the templates.
+      </li>
+    </ul>
+    
+    <p>
+      How to set the log level on template execution depends on the way 
+      the generator is started:
+    </p>
+    <ul>
+      <li>
+        Torque Maven Plugin: set the property loglevel 
+        on the goal generate to trace, debug, info, warn or error.
+      </li>
+      <li>
+        Torque Ant Task: set the property loglevel to true
+        on the Torque generator task to trace, debug, info, warn or error.
+      </li>
+      <li>
+        Plain Java: use the setLoglevel method in the UnitDescriptor
+        you pass in when starting the generator.
+      </li>
+    </ul>
+    
+    <p>
+      Note that the loglevel from the control.xml configuration file
+      is applied after the configuration is read, so the log level before this
+      point may be different.
+    </p>
+    <p>
+      In principle, one can also overwrite the logging behaviour by
+      overwriting the logging configuration file in the class path.
+      (the file used is org.apache.torque.generator.log4j.properties).
+      There are several (typically hacky) ways to do this, depending
+      on your execution environment; one of them is simply exchanging the 
+      logging configuration file in the generator jar you use 
+      (or remove it from the jar and add it to the classpath by another means).
+    </p>
+  </section>
+
+  <section name="Adding debug information to the output">
+    <p>
+     You can add debug information to the currently generated output.
+     This feature is typically switched off but can be switched on
+     per generation run. How to set the flag depends on the way to start the
+     generation:
+    </p>
+    <ul>
+      <li>
+        Torque Maven Plugin: set the property addDebuggingInfoToOutput to true
+        on the goal generate.
+      </li>
+      <li>
+        Torque Ant Task: set the property addDebuggingInfoToOutput to true
+        on the Torque generator task.
+      </li>
+      <li>
+        Plain Java: call setAddDebuggingInfoToOutput(true) on the
+        UnitDescriptor used for the generation.
+      </li>
+    </ul>
+  </section>
+
+  <section name="Logging Implementation for the Torque generator">
+    <p>
+     Note: This section is for people who want to change the underlying logging
+     framework for the Torque generator. This is not needed when using
+     the Torque Maven Plugin or Torque Ant tasks to start the generator.
+    </p>
+    <p>
+     The Torque generator uses  commons-logging as logging abstraction,
+     so in principle, it is logging-framework agnostic.
     </p>
     <p>
       However, the loglevel of the Torque generator can be changed by its
@@ -62,7 +144,5 @@
       By default, the <code>Log4jLoggingAdapter</code> is used.
     </p>
   </section>
-  
-  
  </body>
 </document>
\ No newline at end of file



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message