nicolaken 02/05/30 09:28:18
Modified: src/xdocs/framework book.xml index.xml
src/xdocs book.xml case-studies.xml
src/documentation cocoon.xconf sitemap.xmap
src/xdocs/developing conclusion.xml decomposing.xml
framework.xml implementing.xml index.xml
introduction.xml strategies.xml
Log:
Updating docs generation to Cocoon 2.0.3 used in Centipede;
cleaning the structure related to documentation.
Revision Changes Path
1.13 +1 -1 jakarta-avalon/src/xdocs/framework/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/framework/book.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- book.xml 3 May 2002 10:19:53 -0000 1.12
+++ book.xml 30 May 2002 16:28:17 -0000 1.13
@@ -30,7 +30,7 @@
<menu label="Reference">
<menu-item type="external" id="api-docs" label="API Docs"
href="@AVALON_BASE@/api/index.html"/>
- <menu-item type="external" id="diagrams" label="Diagrams Docs"
href="diagrams/index.html"/>
+ <menu-item type="external" id="diagrams" label="Diagrams Docs"
href="diagrams/"/>
<menu-item label="The Lifecycle" href="reference-the-lifecycle.html"/>
</menu>
1.11 +2 -2 jakarta-avalon/src/xdocs/framework/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/framework/index.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- index.xml 3 May 2002 10:19:53 -0000 1.10
+++ index.xml 30 May 2002 16:28:17 -0000 1.11
@@ -67,7 +67,7 @@
<p>
Besides the
<link href="@AVALON_BASE@/api/index.html">Javadocs</link>, we have
- <link href="diagrams/index.html">Class diagrams</link> and the
+ <link href="diagrams/">Class diagrams</link> and the
<link href="reference-the-lifecycle">The Lifecycle
specification</link>.
</p>
</s1>
@@ -75,7 +75,7 @@
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision: 1.10 $ $Date: 2002/05/03 10:19:53 $
+ $Revision: 1.11 $ $Date: 2002/05/30 16:28:17 $
</legal>
</footer>
</document>
1.13 +2 -12 jakarta-avalon/src/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/book.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- book.xml 19 May 2002 09:53:35 -0000 1.12
+++ book.xml 30 May 2002 16:28:17 -0000 1.13
@@ -11,15 +11,9 @@
<menu-item label="Overview" href="index.html"/>
<menu-item label="Features" href="features.html"/>
<menu-item label="Getting Started" href="framework/getting-started.html"
/>
- <menu-item label="Download" href="download.html" />
+ <menu-item label="Download Binaries"
href="http://jakarta.apache.org/site/binindex.html"; />
+ <menu-item label="Download Source"
href="http://jakarta.apache.org/site/sourceindex.html"; />
<menu-item label="Case Studies" href="case-studies.html" />
-
- <!-- history pages -->
- <menu-item type="hidden" href="history/call-to-vote.html"/>
- <menu-item type="hidden" href="history/what-is-a-server.html"/>
- <menu-item type="hidden" href="history/need-for-avalon.html"/>
- <menu-item type="hidden" href="history/changes.html"/>
-
<menu-item label="License" href="license.html"/>
<menu-item label="Contributors" href="authors/index.html"/>
</menu>
@@ -40,11 +34,7 @@
</menu>
<menu label="For Developers">
- <menu-item label="Changes" href="changes.html" />
<menu-item label="Coding standards" href="code-standards.html" />
- <!--
- <menu-item label="Project structure" href="project-structure.html" />
- -->
<menu-item label="CVS"
href="http://cvs.apache.org/viewcvs/jakarta-avalon/.html"; />
<menu-item label="Mailing Lists" href="mail.html"/>
</menu>
1.2 +2 -2 jakarta-avalon/src/xdocs/case-studies.xml
Index: case-studies.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/case-studies.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- case-studies.xml 19 May 2002 09:53:35 -0000 1.1
+++ case-studies.xml 30 May 2002 16:28:17 -0000 1.2
@@ -15,7 +15,7 @@
<s1 title="Phoenix Applications">
<p>There are a number of applications that are designed to run in the
Phoenix
- kernel. A list of these can be found <link
href="apps/appselsewhere.html">here</link>.</p>
+ kernel. A list of these can be found <link
href="http://jakarta.apache.org/avalon/apps/appselsewhere.html";>here</link>.</p>
</s1>
<s1 title="Avalon Applications">
@@ -28,7 +28,7 @@
<s2 title="Applications Sub-Project">
<p>There are a number of applications currently in work in the
- <link href="apps/appsincvs.html">Applications</link> sub-project,
including
+ <link
href="http://jakarta.apache.org/avalon/apps/appsincvs.html";>Applications</link>
sub-project, including
a RDBMS, FTP server, and XML command server, among others.</p>
</s2>
</s1>
1.3 +367 -156 jakarta-avalon/src/documentation/cocoon.xconf
Index: cocoon.xconf
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/documentation/cocoon.xconf,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- cocoon.xconf 11 Sep 2001 17:53:49 -0000 1.2
+++ cocoon.xconf 30 May 2002 16:28:17 -0000 1.3
@@ -1,117 +1,235 @@
-<?xml version="1.0"?>
+<?xml version="1.0" encoding="UTF-8"?>
<cocoon version="2.0">
+<!-- ================ Apache Cocoon configuration file ================== -->
+<!-- For full description of the components and their parameters ...
+ - Apache Cocoon User Documentation at /userdocs/
+ - webapp/cocoon.xconf (this file) - describes each core component
+ - each optional component/.../*.xconf - these describe the parameters
+ for each component and are automatically included at build-time.
+
+ The notes that accompany the settings below are intended to be concise.
+-->
+
<!-- ===================== General Components =========================== -->
- <!-- The default parser used in the Apache Cocoon 2 system is
- org.apache.cocoon.components.parser.JaxpParser.
- Apache Cocoon 2 system requires a JAXP 1.1 parser.
- If you have problems because your servlet environment uses its own
- parser not conforming to JAXP 1.1 try using the alternative
- XercesParser instead of the JaxpParser. To activate the XercesParser
- move the line below starting with <parser ...> out of this comment
block.
- You also than have to add a system property to your JVM
- (probably on the startup of your servlet engine like this:
-
-
-Dorg.apache.cocoon.components.parser.Parser=org.apache.cocoon.components.parser.XercesParser
-
- <parser class="org.apache.cocoon.components.parser.XercesParser"/>
- -->
-
- <!-- Storing:
- freememory: Indicates how much memory should be left free in the
- JVM for normal operation.
- heapsize: Indicates how big the heap size can grow to before the
- cleanup thread kicks in.
- objectlifetime: Indicates how long (seconds) a cache object will
- be hold in memory. The object will be thrown out,
- when the time is over.
- interval: Indicates the interval of the cleanup thread in seconds.
- maxobjects: Indicates how many objects will be hold in the cache.
- When the number of maxobjects has been reached. The
- last object in the cache will be thrown out.
- usethread: Indicates whether we use a cleanup thread or not.
- threadpriority: Indicates the priority of the cleanup thread.
- (1 is the lowest priority and 10 is the highest).
+ <!-- Parser:
+ The default parser used in Apache Cocoon is
+ org.apache.avalon.excalibur.xml.JaxpParser. Apache Cocoon requires a
+ JAXP 1.1 parser.
+ If you have problems because your servlet environment uses its own
+ parser not conforming to JAXP 1.1 try using the alternative
+ XercesParser instead of the JaxpParser. To activate the XercesParser,
+ change the class attribute to
+ class="org.apache.avalon.excalibur.xml.XercesParser"
+ You will also need to add a system property to your JVM,
+ probably on the startup of your servlet engine like this:
+
-Dorg.apache.avalon.excalibur.xml.Parser=org.apache.avalon.excalibur.xml.XercesParser
+
+ Configuration for the JaxpParser (not the XercesParser!):
+ - validate (boolean, default = false): This parameter causes the parser
+ to be a validating parser.
+ XML validation is only being used for the documentation build.
+ (If you are going to use it elsewhere, then do so with caution.)
+ You really should have validated all of your XML documents already,
+ according to their proper DTD or schema. Do not expect Cocoon to do
it.
+ - namespace-prefixes (boolean, default = false) : do we want
+ namespaces declarations also as 'xmlns:' attributes ?
+ Note : setting this to true confuses some XSL processors (e.g.
Saxon).
+ - stop-on-warning (boolean, default = true) : should the parser
+ stop parsing if a warning occurs ?
+ - stop-on-recoverable-error (boolean, default = true) : should the parser
+ stop parsing if a recoverable error occurs ?
+ - reuse-parsers (boolean, default = true) : do we want to reuse
+ parsers or create a new parser for each parse ?
+ Note : even if this parameter is true, parsers are not
+ recycled in case of parsing errors : some parsers (e.g. Xerces)
don't like
+ to be reused after failure.
+ - sax-parser-factory (string) : the name of the SAXParserFactory
+ implementation class to be used instead of using the standard JAXP
mechanism
+ (SAXParserFactory.newInstance()). This allows to choose
+ unambiguously the JAXP implementation to be used when several of
them are
+ available in the classpath.
+ - document-builder-factory (string) : the name of the
+ DocumentBuilderFactory implementation to be used (similar to
+ sax-parser-factory for DOM).
+ -->
+ <xml-parser class="org.apache.avalon.excalibur.xml.JaxpParser"
logger="core.xml-parser">
+ <parameter name="validate" value="false"/>
+ <parameter name="namespace-prefixes" value="false"/>
+ <parameter name="stop-on-warning" value="true"/>
+ <parameter name="stop-on-recoverable-error" value="true"/>
+ <parameter name="reuse-parsers" value="false"/>
+ <!--
+ <parameter name="sax-parser-factory" value="???"/>
+ <parameter name="document-builder-factory" value="???"/>
+ -->
+ </xml-parser>
+
+ <!-- ============================ STORE ============================ -->
+ <!-- Persistent store for the cache. Two store implementations to choose
+ from:
+ * FilesystemStore: Simple. Dependable. Thorougly tested.
+ * JispFilesystemStore: Scalable. New kid on the block.
+
+ Common configuration parameters:
+ use-cache-directory: Indicates that cache directory specified in
+ web.xml should be used.
+ use-work-directory: Indicates that work directory specified in
+ web.xml should be used.
+ directory: Specifies directory to use. Absolute or relative to the
+ work directory.
-->
- <store class="org.apache.cocoon.components.store.MRUMemoryStore">
+ <cache-persistent
class="org.apache.cocoon.components.store.FilesystemStore"
logger="core.store.persistent">
+ <parameter name="use-cache-directory" value="true"/>
+ </cache-persistent>
+
+ <!-- Memory Storing: -->
+ <cache-transient class="org.apache.cocoon.components.store.MRUMemoryStore"
logger="core.store.transient">
+ <!-- Indicates how many objects will be hold in the cache.
+ When the number of maxobjects has been reached. The last object in the
+ cache will be thrown out. -->
<parameter name="maxobjects" value="100"/>
- <parameter name="threadpriority" value="5"/>
- <parameter name="filesystem" value="true"/>
- </store>
+
+ <!-- Turns the swapping of the objects into persistent cache on
+ and off. -->
+ <parameter name="use-persistent-cache" value="true"/>
+ </cache-transient>
<!-- Store Janitor:
- freememory = How much free memory shall be available in the jvm
- heapsize = Indicates the limit of the jvm memory consumption
- cleanupthreadinterval = How often shall the cleanup thread check memory
- threadpriority = Indicates the thread priority of the cleanup thread
-
- Be carefull with the heapsize and freememory paramters. Wrong values can
- cause high cpu usage.
- Example configuration:
+ Be careful with the heapsize and freememory parameters. Wrong values can
+ cause high cpu usage. Example configuration:
Jvm settings:
- -Xms100000000 -Xmx200000000
+ -Xmx200000000
store-janitor settings:
- <parameter name="freememory" value="50000000"/>
+ <parameter name="freememory" value="5000000"/>
<parameter name="heapsize" value="150000000"/>
- Heapsize must be higher then the -Xms parameter and freememory
- between those both.
+ It is recommended to have heapsize equal to -Xmx, especially
+ on Sun's JVM which are unable to shrink its heap once it grows above
minimum.
+ Freememory should be greater than amount of memory necessary for normal
+ application operation.
-->
- <store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl"
logger="root.store">
+ <store-janitor class="org.apache.cocoon.components.store.StoreJanitorImpl"
logger="core.store.janitor">
+ <!-- How much free memory shall be available in the jvm -->
<parameter name="freememory" value="1000000"/>
- <parameter name="heapsize" value="60000000"/>
+ <!-- Indicates the limit of the jvm memory consumption. The default max
+ heapsize for Sun's JVM is 64Mb -->
+ <parameter name="heapsize" value="67108864"/>
+ <!-- How often shall the cleanup thread check memory -->
<parameter name="cleanupthreadinterval" value="10"/>
+ <!-- Indicates the thread priority of the cleanup thread -->
<parameter name="threadpriority" value="5"/>
+ <!-- How much percent of the elements of each registered Store shall
+ be removed when low on memory. Default 10% -->
+ <parameter name="percent_to_free" value="10"/>
</store-janitor>
+ <!-- ============================ STORE END ========================= -->
- <xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl"
logger="root.xslt">
+ <!-- XSLT Processor:
+ For Xalan: Turn 'incremental-processing' to true if you want a continous
output (if set to false the transformer
+ delivers SAX events after all transformations has been done). -->
+ <xslt-processor
class="org.apache.cocoon.components.xslt.XSLTProcessorImpl"
logger="core.xslt-processor">
<parameter name="use-store" value="true"/>
+ <parameter name="incremental-processing" value="false"/>
</xslt-processor>
- <!-- The url factory adds special url protocols to the system, they
- are then available inside Cocoon, e.g. as a source argument
- for one of the sitemap components -->
- <url-factory>
- <protocol name="resource"
class="org.apache.cocoon.components.url.ResourceURLFactory"/>
- <protocol name="context"
class="org.apache.cocoon.components.url.ContextURLFactory"/>
+ <!-- Xpath Processor:
+ -->
+ <xpath-processor
class="org.apache.avalon.excalibur.xml.xpath.XPathProcessorImpl"
logger="core.xpath-processor"/>
+
+ <!-- URL Factory:
+ The url factory adds special url protocols to the system, they are then
+ available inside Cocoon, e.g. as a source argument for one of the sitemap
+ components.
+ -->
+ <url-factory logger="core.url-factory">
+ <!-- Allows access to resources available from the ClassLoader,
+ using getResource() method. -->
+ <protocol class="org.apache.cocoon.components.url.ResourceURLFactory"
name="resource"/>
+ <!-- Allows access to resources available from the servlet context,
+ using getResource() method. -->
+ <protocol class="org.apache.cocoon.components.url.ContextURLFactory"
name="context"/>
+ <!-- Add here protocol factories for your own protocols -->
</url-factory>
- <!-- The source handler adds special url protocols to the system, they
- are then available inside Cocoon, e.g. as a source argument
- for one of the sitemap components. -->
- <source-handler>
- </source-handler>
+ <!-- Source Handler:
+ The source handler adds special url protocols to the system, they are
+ then available inside Cocoon, e.g. as a source argument for one of the
+ sitemap components.
+ -->
+ <source-handler logger="core.source-handler">
+ <!-- file protocol : this is a WriteableSource -->
+ <protocol class="org.apache.cocoon.components.source.FileSourceFactory"
name="file"/>
+
+
- <program-generator>
+ <!-- xmldb pseudo protocol -->
+ <protocol class="org.apache.cocoon.components.source.XMLDBSourceFactory"
name="xmldb">
+ <!-- Xindice driver -->
+ <driver class="org.apache.xindice.client.xmldb.DatabaseImpl"
type="xindice"/>
+ <!-- Add here other XML:DB compliant databases drivers -->
+ </protocol>
+</source-handler>
+
+ <!-- Program Generator:
+ The ProgamGenerator builds programs from a XML document written in a
+ MarkupLanguage.
+ auto-reload:
+ root-package: persistent code repository.
+ preload:
+ -->
+ <program-generator logger="core.program-generator">
<parameter name="auto-reload" value="true"/>
<parameter name="root-package" value="org.apache.cocoon.www"/>
<parameter name="preload" value="true"/>
</program-generator>
+ <!-- Xscript:
+ -->
+ <xscript logger="core.xscript">
+ <parameter name="xscript:copy-of"
value="resource://org/apache/cocoon/components/xscript/xslt/copy-of.xsl"/>
+ <parameter name="xscript:value-of"
value="resource://org/apache/cocoon/components/xscript/xslt/value-of.xsl"/>
+ </xscript>
+
+ <!-- Programming Languages: -->
<programming-languages>
- <java-language name="java">
- <!-- compiler parameter specifies which class to use to compile Java.
- Possible variants are Javac and Jikes compilers.
- Javac requires javac.jar (included with Cocoon distribution).
- Jikes requires IBM jikes compiler to be present in the PATH -->
- <parameter name="compiler"
value="org.apache.cocoon.components.language.programming.java.Javac"/>
+ <java-language logger="core.language.java" name="java">
<!-- Specifies which formatter to use to format source code.
- This parameter is optional. -->
- <!-- A singleton-like implementation of a ClassLoader -->
+ This parameter is optional.
+ It is commented out because of bug #5689: Java "code-formatter"
incorrectly formats double values
+ <parameter name="code-formatter"
value="org.apache.cocoon.components.language.programming.java.JstyleFormatter"/>
+ -->
+ <!-- A singleton-like implementation of a ClassLoader -->
<parameter name="class-loader"
value="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
- </java-language>
- </programming-languages>
+
+ <!-- Compiler parameter specifies which class to use to compile Java.
+ Possible variants are:
+ Javac. Requires javac.jar (included with JDK as lib/toools.jar).
+ Pizza. Requires pizza.jar (included with Cocoon distribution).
+ Jikes. Requires IBM jikes compiler to be present in the PATH
-->
+ <parameter name="compiler"
value="org.apache.cocoon.components.language.programming.java.Pizza"/>
+</java-language>
- <classloader
class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"/>
+</programming-languages>
+ <!-- Class loader:
+ A singleton-like implementation of a ClassLoader.
+ -->
+ <classloader
class="org.apache.cocoon.components.classloader.ClassLoaderManagerImpl"
logger="core.classloader"/>
+
+ <!-- Markup Languages:
+ This section defines several builtin logicsheets. A logicsheet is an XML
+ filter used to translate user-defined, dynamic markup into equivalent
+ code embedding directives for a given markup language.
+ -->
<markup-languages>
- <xsp-language name="xsp">
+ <xsp-language logger="core.markup.xsp" name="xsp">
<parameter name="prefix" value="xsp"/>
<parameter name="uri" value="http://apache.org/xsp"/>
- <!-- Defines the XSP Core logicsheet for the Java language -->
<target-language name="java">
+ <!-- Defines the XSP Core logicsheet for the Java language -->
<parameter name="core-logicsheet"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xsp.xsl"/>
<!-- The Request logicsheet (taglib) is an XSP logicsheet that wraps
XML tags
@@ -135,11 +253,13 @@
XML interface to most methods of the HttpSession object (see
the Java Servlet API
Specification, version 2.2 ) for more information. -->
<builtin-logicsheet>
- <parameter name="prefix" value="session"/>
+ <parameter name="prefix" value="xsp-session"/>
<parameter name="uri" value="http://apache.org/xsp/session/2.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/session.xsl"/>
</builtin-logicsheet>
+ <!-- The Cookie logicsheet (taglib) is an XSP logicsheet that wraps
XML tags
+ around standard cookie operations -->
<builtin-logicsheet>
<parameter name="prefix" value="xsp-cookie"/>
<parameter name="uri" value="http://apache.org/xsp/cookie/2.0"/>
@@ -175,6 +295,23 @@
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/form-validator.xsl"/>
</builtin-logicsheet>
+ <!-- The sel taglib allows to put multiple pages / view into
+ one xsp. While in general it is good style to put
+ different views into different xsp because they're more
+ easily maintained, this is a useful feature with
+ e.g. with long forms that are broken into parts -->
+ <builtin-logicsheet>
+ <parameter name="prefix" value="sel"/>
+ <parameter name="uri" value="http://apache.org/xsp/sel/1.0"/>
+ <parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/sel.xsl"/>
+ </builtin-logicsheet>
+
+ <builtin-logicsheet>
+ <parameter name="prefix" value="action"/>
+ <parameter name="uri" value="http://apache.org/cocoon/action/1.0"/>
+ <parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/action.xsl"/>
+ </builtin-logicsheet>
+
<!-- The capture taglib is for capturing parts of the XSP-generated
XML as
XML fragments or DOM nodes -->
<builtin-logicsheet>
@@ -183,11 +320,23 @@
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/capture.xsl"/>
</builtin-logicsheet>
+ <builtin-logicsheet>
+ <parameter name="prefix" value="xscript"/>
+ <parameter name="uri" value="http://apache.org/xsp/xscript/1.0"/>
+ <parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/xscript.xsl"/>
+ </builtin-logicsheet>
+
+ <builtin-logicsheet>
+ <parameter name="prefix" value="soap"/>
+ <parameter name="uri" value="http://apache.org/xsp/soap/3.0"/>
+ <parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/soap.xsl"/>
+ </builtin-logicsheet>
</target-language>
- </xsp-language>
+
+</xsp-language>
<!-- Defines Sitemap Core logicsheet for the Java language -->
- <sitemap-language name="sitemap">
+ <sitemap-language logger="core.markup.sitemap" name="sitemap">
<parameter name="prefix" value="map"/>
<parameter name="uri" value="http://apache.org/cocoon/sitemap/1.0"/>
@@ -197,92 +346,154 @@
</sitemap-language>
</markup-languages>
- <!-- A StreamPipeline either
- collects a Reader and let it produce a character stream
- or connects a EventPipeline with a
- Serializer and let them produce the character stream.
- -->
- <stream-pipeline
class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"
- pool-max="32" pool-min="16" pool-grow="4"/>
-
- <!-- Caching of stream pipeline:
- freememory: Indicates how much memory should be left free in the
- JVM for normal operation.
- heapsize: Indicates how big the heap size can grow to before the
- cleanup thread kicks in.
- objectlifetime: Indicates how long (seconds) a cache object will
- be hold in memory. The object will be thrown out,
- when the time is over.
- interval: Indicates the interval of the cleanup thread in seconds.
- maxobjects: Indicates how many objects will be hold in the cache.
- When the number of maxobjects has been reached. The
- last object in the cache will be thrown out.
- usethread: Indicates whether we use a cleanup thread or not.
- threadpriority: Indicates the priority of the cleanup thread.
- (1 is the lowest priority and 10 is the highest).
+ <!-- Stream Pipeline:
+ Either collects a Reader and lets it produce a character stream
+ or connects an EventPipeline with a Serializer and lets them produce
+ the character stream. Alternatives to CachingStreamPipeline are:
+ <stream-pipeline
class="org.apache.cocoon.components.pipeline.NonCachingStreamPipeline"/>
-->
- <stream-cache class="org.apache.cocoon.components.store.MRUMemoryStore"
logger="root.store">
- <parameter name="maxobjects" value="100"/>
- <parameter name="threadpriority" value="5"/>
- <parameter name="filesystem" value="true"/>
- </stream-cache>
+ <stream-pipeline
class="org.apache.cocoon.components.pipeline.CachingStreamPipeline"
logger="core.stream-pipeline" pool-grow="4" pool-max="32" pool-min="8"/>
- <!-- An EventPipeline connects the generator and the various transformers
- and produces a character stream. Alternatives to CachingEventPipeline
- are: NonCachingEventPipeline.
- <event-pipeline
class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
- -->
- <event-pipeline
class="org.apache.cocoon.components.pipeline.CachingEventPipeline"
- pool-max="32" pool-min="16" pool-grow="4"/>
-
- <!-- Caching of event pipeline:
- freememory: Indicates how much memory should be left free in the
- JVM for normal operation.
- heapsize: Indicates how big the heap size can grow to before the
- cleanup thread kicks in.
- objectlifetime: Indicates how long (seconds) a cache object will
- be hold in memory. The object will be thrown out,
- when the time is over.
- interval: Indicates the interval of the cleanup thread in seconds.
- maxobjects: Indicates how many objects will be hold in the cache.
- When the number of maxobjects has been reached. The
- last object in the cache will be thrown out.
- usethread: Indicates whether we use a cleanup thread or not.
- threadpriority: Indicates the priority of the cleanup thread.
- (1 is the lowest priority and 10 is the highest).
+ <!-- Event Pipeline:
+ Connects the generator and the various transformers and produces a
+ character stream. Alternatives to CachingEventPipeline are:
+ <event-pipeline
class="org.apache.cocoon.components.pipeline.NonCachingEventPipeline"/>
+ <event-pipeline
class="org.apache.cocoon.components.profiler.ProfilingCachingEventPipeline"/>
+ <event-pipeline
class="org.apache.cocoon.components.profiler.ProfilingNonCachingEventPipeline"/>
-->
- <event-cache class="org.apache.cocoon.components.store.MRUMemoryStore"
logger="root.store">
- <parameter name="maxobjects" value="100"/>
- <parameter name="threadpriority" value="5"/>
- <parameter name="filesystem" value="true"/>
- </event-cache>
+ <event-pipeline
class="org.apache.cocoon.components.pipeline.CachingEventPipeline"
logger="core.event-pipeline" pool-grow="4" pool-max="32" pool-min="8"/>
+
+ <!-- Compiling xml to byte streams.
+ The xml-serializer "compiles" xml sax events into a byte stream
+ and the xml-deserializer does the same vice versa.
+ Make sure, that if you change one of these components, that you
+ may have to change the other one as well, as they might have
+ a dependency.
+ -->
+ <xml-serializer
class="org.apache.cocoon.components.sax.XMLByteStreamCompiler"
logger="core.xml-serializer"/>
- <!-- The SAXConnector connects the various pipeline components.
- LoggingSAXConnector logs SAX events between pipeline components
- into a cocoon's log file.
- Uncomment one of the following lines for using the SAXConnector.
+ <xml-deserializer
class="org.apache.cocoon.components.sax.XMLByteStreamInterpreter"
logger="core.xml-deserializer"/>
+
+ <!-- SAXConnector:
+ Connects the various pipeline components.
+ LoggingSAXConnector logs SAX events between pipeline components
+ into cocoon's log file.
+ ProfilingSAXConnector gathers timing information.
+ Uncomment one of the following lines for using the SAXConnector.
<sax-connector
class="org.apache.cocoon.components.saxconnector.LoggingSAXConnector"/>
+ <sax-connector
class="org.apache.cocoon.components.profiler.ProfilingSAXConnector"/>
+ -->
+
+ <!-- Resource Monitor:
+ The Monitor keeps track on changes to a Resource.
-->
+ <monitor logger="core.monitor">
+ <thread frequency="10000" priority="5"/>
+ </monitor>
<!-- ======================== The sitemap ============================== -->
- <!-- The reloading of the sitemap:
- The check-reload attribute determines if the sitemap is reloaded on
change. If
- it is set to "no", the sitemap is generated once at startup, if it
is set to "yes",
- the sitemap is regenerated if it changes.
- The reload-method specifies the method for the regeneration:
- asynchron: If the sitemap changes, the sitemap is regenerated at the
next request in
- the background and the incoming request is served
with the old sitemap.
- All subsequent requests are served with the old
sitemap until the
- regeneration in the background has finished.
- synchron: If the sitemap changes, the sitemap is regenerated at the
next request.
- When the regeneration is finished the request (and
all subsequent ones)
- is served with the new sitemap.
-
- For development environment set the reload-method to synchron and the
- check-reload to yes, for production environment it is advisable to
set
- the reload-method to asynchron and for more safety the check-reload
to no.
- -->
- <sitemap file="sitemap.xmap" reload-method="asynchron" check-reload="yes"/>
+ <!--
+ Compiled sitemap engine. This is the original engine, that is now
replaced
+ by the interpreted engine (see above).
+
+ If you want to use this engine, uncomment this element and comment the
+ defaut one below.
+
+ Reloading of the sitemap:
+ The check-reload attribute determines if the sitemap is reloaded on
change.
+ Set to "no", the sitemap is generated once at startup.
+ Set to "yes", the sitemap is regenerated if it changes.
+
+ The reload-method specifies the method for the regeneration:
+ asynchron: WARNING: this reload method is broken and won't be fixed.
+ Synchron is now made default and preferred reload method.
+ synchron: If the sitemap changes, the sitemap is regenerated at the
+ next request. When the regeneration is finished, the request
+ (and all subsequent ones) is served with the new sitemap.
+ For development environment, set the check-reload to yes.
+ For production environment, it is advisable to set the check-reload to
no.
+
+ <sitemap check-reload="yes"
class="org.apache.cocoon.sitemap.SitemapManager" file="sitemap.xmap"
logger="sitemap" reload-method="synchron"/>
+ -->
+
+ <!--
+ New implementation of the sitemap. It is interpreted, so load times are
super-fast,
+ and request processing is slightly faster than with the compiled engine
thanks to
+ the HotSpot VM.
+
+ Reloading of the sitemap:
+ The check-reload attribute determines if the sitemap is reloaded on
change.
+ Set to "no", the sitemap is generated once at startup.
+ Set to "yes", the sitemap is regenerated if it changes.
+
+ For development environment, set the check-reload to yes.
+ For production environment, it is advisable to set the check-reload to
no.
+ -->
+ <sitemap file="sitemap.xmap" check-reload="yes" logger="sitemap"/>
+
+
+ <!-- Entity resolution catalogs:
*********************************************
+ catalog:
+ The default catalog is distributed at /resources/entities/catalog
+ This is the contextual pathname for Cocoon resources.
+ You can override this path, if necessary, using the "catalog" parameter.
+ <parameter name="catalog" value="/resources/entities/catalog"/>
+ However, it is probably desirable to leave this default catalog config
+ and declare your own local catalogs, which are loaded in addition to
+ the system catalog.
+
+ There are various ways to do local configuration (see "Entity Catalogs"
+ documentation). One way is via the CatalogManager.properties file.
+ As an additional method, you can specify the "local-catalog" parameter
here.
+
+ local-catalog:
+ The full filesystem pathname to a single local catalog file.
+ <parameter name="local-catalog" value="/usr/local/sgml/mycatalog"/>
+
+ verbosity:
+ The level of messages for status/debug (messages go to standard output)
+ The following messages are provided ...
+ 0 = none
+ 1 = ? (... not sure yet)
+ 2 = 1+, Loading catalog, Resolved public, Resolved system
+ 3 = 2+, Catalog does not exist, resolvePublic, resolveSystem
+ 10 = 3+, List all catalog entries when loading a catalog
+ (Cocoon also logs the "Resolved public" messages.)
+ TODO: determine all messages at each level
+ <parameter name="verbosity" value="2"/>
+
+ **************************************************************************
-->
+ <entity-resolver
class="org.apache.cocoon.components.resolver.ResolverImpl"
logger="core.resolver">
+ <parameter name="catalog" value="/resources/schema/catalog"/>
+ <parameter name="verbosity" value="1"/>
+ </entity-resolver>
+
+ <!-- Persistent store for the cache. Two store implementations to choose
+ from:
+ * FilesystemStore: Simple. Dependable. Thorougly tested.
+ * JispFilesystemStore: Scalable. New kid on the block. Not
thorougly tested.
+ If you opt in to use JispFilesystemStore, comment out FilesystemStore
+ entry.
+
+ JispFilesystemStore configuration parameters
+ (in addition to common parameters):
+ datafile: name of the store file to use.
+ indexfile: name of the index file to use.
+ order: FIXME: put description here.
+
+ <cache-persistent
class="org.apache.cocoon.components.store.JispFilesystemStore"
+ logger="core.store.persistent">
+ <parameter name="use-cache-directory" value="true"/>
+ <parameter name="datafile" value="cocoon-cache.dat"/>
+ <parameter name="indexfile" value="cocoon-cache.idx"/>
+ <parameter name="order" value="1701"/>
+ </cache-persistent>
+ -->
</cocoon>
+
+
+
+
+
1.12 +232 -55 jakarta-avalon/src/documentation/sitemap.xmap
Index: sitemap.xmap
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/documentation/sitemap.xmap,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- sitemap.xmap 31 Jan 2002 17:38:18 -0000 1.11
+++ sitemap.xmap 30 May 2002 16:28:17 -0000 1.12
@@ -8,6 +8,8 @@
<map:generators default="file">
<map:generator name="file"
src="org.apache.cocoon.generation.FileGenerator" label="content"/>
+ <!-- FIXME: Change this once better view handling is implemented -->
+ <map:generator name="file-nolabel"
src="org.apache.cocoon.generation.FileGenerator"/>
</map:generators>
<map:transformers default="xslt">
@@ -15,7 +17,7 @@
<use-request-parameters>false</use-request-parameters>
<use-browser-capabilities-db>false</use-browser-capabilities-db>
</map:transformer>
- <map:transformer name="xinclude"
src="org.apache.cocoon.transformation.XIncludeTransformer"/>
+ <map:transformer name="xinclude"
src="org.apache.cocoon.transformation.XIncludeTransformer"/>
</map:transformers>
<map:readers default="resource">
@@ -26,14 +28,40 @@
<map:serializer name="html" mime-type="text/html"
src="org.apache.cocoon.serialization.HTMLSerializer">
<encoding>iso8859-1</encoding>
</map:serializer>
- <map:serializer name="xml" mime-type="text/xml"
src="org.apache.cocoon.serialization.XMLSerializer"/>
- <map:serializer name="links"
src="org.apache.cocoon.serialization.LinkSerializer"/>
- <map:serializer name="fo2pdf" mime-type="application/pdf"
src="org.apache.cocoon.serialization.FOPSerializer"/>
+
+ <map:serializer name="html-loose" mime-type="text/html"
src="org.apache.cocoon.serialization.HTMLSerializer">
+ <doctype-public>-//CollabNet//DTD XHTML 1.0
Transitional//EN</doctype-public>
+
<doctype-system>http://collabnet.com/dtds/collabnet_transitional_10.dtd</doctype-system>
+ <encoding>iso8859-1</encoding>
+ <omit-xml-declaration>yes</omit-xml-declaration>
+ </map:serializer>
+ <map:serializer name="pdf" mime-type="application/pdf"
src="org.apache.cocoon.serialization.FOPSerializer">
+ <encoding>iso8859-1</encoding>
+ </map:serializer>
+ <map:serializer name="xml" mime-type="text/xml"
src="org.apache.cocoon.serialization.XMLSerializer">
+ <encoding>iso8859-1</encoding>
+ </map:serializer>
+ <map:serializer name="links"
src="org.apache.cocoon.serialization.LinkSerializer">
+ <encoding>iso8859-1</encoding>
+ </map:serializer>
</map:serializers>
<map:matchers default="wildcard">
<map:matcher name="wildcard"
src="org.apache.cocoon.matching.WildcardURIMatcher"/>
</map:matchers>
+<!--
+ <map:selectors default="skin-parameter">
+ <map:selector name="request-parameter"
logger="sitemap.selector.request-parameter"
+ src="org.apache.cocoon.selection.RequestParameterSelector">
+ <parameter-name>skin</parameter-name>
+ </map:selector>
+ <map:selector name="style-parameter"
logger="sitemap.selector.request-parameter"
+ src="org.apache.cocoon.selection.RequestParameterSelector">
+ <parameter-name>style</parameter-name>
+ </map:selector>
+
+ </map:selectors>
+-->
</map:components>
<!-- =========================== Views ===================================
-->
@@ -44,98 +72,247 @@
</map:view>
<map:view name="links" from-position="last">
- <map:transform src="stylesheets/filterlinks.xsl"/>
+ <map:transform src="library/xslt/filterlinks.xsl"/>
<map:serialize type="links"/>
</map:view>
-
</map:views>
+ <map:resources>
+ <map:resource name="skinit">
+ <map:transform src="skins/@skin@/xslt/html/{type}.xsl"/>
+ <map:serialize/>
+ </map:resource>
+
+ <map:resource name="skin-read">
+ <map:read src="skins/@skin@/{path}" mime-type="{mime-type}"/>
+ </map:resource>
+
+ </map:resources>
+
<!-- =========================== Pipelines =================================
-->
<map:pipelines>
+
<map:pipeline>
+
<map:match pattern="">
<map:redirect-to uri="index.html"/>
</map:match>
+
+ <!--
- <map:match pattern="**book.xml">
- <map:generate src="xdocs/{1}book.xml"/>
- <map:transform src="stylesheets/book2menu.xsl"/>
- <map:serialize type="xml"/>
+ <map:pipeline>
+ <map:match pattern="">
+ <map:redirect-to uri="page3333.html"/>
</map:match>
- <map:match pattern="body-**.xml">
- <map:generate src="xdocs/{1}.xml"/>
- <map:transform src="stylesheets/document2docbook.xsl"/>
- <map:transform src="stylesheets/docbook2body.xsl"/>
+ <map:match pattern="*[*].html">
+ <map:aggregate element="site" label="content">
+ <map:part src="site.xml" />
+ <map:part src="index.xml"/>
+ <map:part src="{1}.xml" element="book"/>
+ </map:aggregate>
+ <map:transform src="site2html.xsl">
+ <map:parameter name="page-index" value="{2}"/>
+ <map:parameter name="page-count" value="5"/>
+ <map:parameter name="page-name" value="{1}"/>
+ </map:transform>
+ <map:serialize/>
+ </map:match>
+-->
+
+ <map:match pattern="**book-**.xml">
+ <map:generate src="content/xdocs/{1}book.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="book2menu"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="body-todo.xml">
+ <map:generate type="file-nolabel" src="content/xdocs/todo.xml"/>
+ <map:transform src="library/xslt/todo2document.xsl" label="content"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="body-changes.xml">
+ <map:generate type="file-nolabel" src="content/xdocs/changes.xml"/>
+ <map:transform src="library/xslt/changes2document.xsl" label="content"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="body-faq.xml">
+ <map:generate type="file-nolabel" src="content/xdocs/faq.xml"/>
+ <map:transform src="library/xslt/faq2document.xsl" label="content"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="body-developing/*.xml">
+ <map:generate type="file-nolabel"
src="content/xdocs/developing/{1}.xml" />
+ <map:transform src="library/xslt/docbook2body.xsl" label="content"/>
+ <map:serialize type="xml"/>
+ </map:match>
+
+ <map:match pattern="body-authors/*.xml">
+ <map:generate type="file-nolabel" src="content/xdocs/authors/{1}.xml" />
+ <map:transform src="library/xslt/docbook2body.xsl" label="content"/>
+ <map:serialize type="xml"/>
+ </map:match>
+
+ <!-- Generate the "doclist" - list of all documentation
+ The first match generates each book.xml and adds a new attribute "uri".
+ The second match aggregates each book.xml into a doclist and
+ then converts it to a document.
+ -->
+ <map:match pattern="doclist/content/xdocs/**book.xml">
+ <map:generate src="content/xdocs/{1}book.xml"/>
+ <map:transform src="library/xslt/doclist.xsl">
+ <map:parameter name="uri" value="{1}"/>
+ </map:transform>
<map:serialize type="xml"/>
</map:match>
-
- <map:match pattern="*.html">
- <map:aggregate element="site">
- <map:part src="cocoon:/book.xml"/>
- <map:part src="cocoon:/body-{1}.xml"/>
- </map:aggregate>
- <map:transform src="stylesheets/site2xhtml.xsl"/>
- <map:serialize/>
+
+ <map:match pattern="body-doclist.xml">
+ <map:aggregate element="doclist">
+ <map:part src="cocoon:/doclist/content/xdocs/book.xml"/>
+ </map:aggregate>
+ <map:transform src="library/xslt/doclist2document.xsl"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
</map:match>
-
- <map:match pattern="**developing-with-avalon.pdf">
- <map:generate src="xdocs/developing/index.xml"/>
- <map:transform type="xinclude"/>
- <map:transform src="stylesheets/docbook2fo.xsl"/>
- <map:serialize type="fo2pdf"/>
+
+ <map:match pattern="body-**.xml">
+ <map:generate src="content/xdocs/{1}.xml"/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="document2html"/>
+ </map:call>
</map:match>
- <map:match pattern="**diagrams/*.html">
- <map:read src="diagrams/{2}.html" mime-type="text/html"/>
+ <map:match pattern="developing/*.html">
+ <map:aggregate element="site">
+ <map:part src="cocoon:/developing/book-developing/{1}.xml"/>
+ <map:part src="cocoon:/body-developing/{1}.xml"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ </map:call>
</map:match>
- <map:match pattern="api/**.html">
- <!-- dummy: can't "ignore" certain uris -->
- <map:read src="xdocs/index.xml" mime-type="text/xml"/>
+ <map:match pattern="authors/*.html">
+ <map:aggregate element="site">
+ <map:part src="cocoon:/authors/book-authors/{1}.xml"/>
+ <map:part src="cocoon:/body-authors/{1}.xml"/>
+ </map:aggregate>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ </map:call>
</map:match>
-
- <map:match pattern="developing/*.html">
+
+ <map:match pattern="*.html">
<map:aggregate element="site">
- <map:part src="cocoon:/developing/book.xml"/>
- <map:part src="cocoon:/body-developing/{1}.xml"/>
+ <map:part src="cocoon:/book-{1}.xml"/>
+ <map:part src="cocoon:/body-{1}.xml" label="content"/>
</map:aggregate>
- <map:transform src="stylesheets/site2xhtml.xsl"/>
- <map:serialize/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ </map:call>
</map:match>
<map:match pattern="**/*.html">
<map:aggregate element="site">
- <map:part src="cocoon:/{1}/book.xml"/>
- <map:part src="cocoon:/body-{1}/{2}.xml"/>
+ <map:part src="cocoon:/{1}/book-{1}/{2}.xml"/>
+ <map:part src="cocoon:/body-{1}/{2}.xml" label="content"/>
</map:aggregate>
- <map:transform src="stylesheets/site2xhtml.xsl"/>
- <map:serialize/>
+ <map:call resource="skinit">
+ <map:parameter name="type" value="site2xhtml"/>
+ </map:call>
</map:match>
+
+
+<!-- -->
+ <map:match pattern="**developing-with-avalon.pdf">
+ <map:generate src="content/xdocs/developing/index.xml"/>
+ <map:transform type="xinclude"/>
+ <map:transform src="library/xslt/docbook2fo.xsl"/>
+ <map:serialize type="pdf"/>
+ </map:match>
+<!-- -->
<!-- ================ Static =========================== -->
+
+ <map:match pattern="skin/**.js">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="scripts/{1}.js"/>
+ <map:parameter name="mime-type" value="application/javascript"/>
+ </map:call>
+ </map:match>
- <map:match pattern="**images/*.png">
- <map:read src="resources/images/{2}.png" mime-type="image/png"/>
+ <map:match pattern="**/skin/**.js">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="scripts/{2}.js"/>
+ <map:parameter name="mime-type" value="application/javascript"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="**.js">
+ <map:read src="resources/scripts/{1}.js"
mime-type="application/javascript"/>
+ </map:match>
+
+ <map:match pattern="skin/**.css">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="css/{1}.css"/>
+ <map:parameter name="mime-type" value="text/css"/>
+ </map:call>
</map:match>
- <map:match pattern="**images/*.jpg">
- <map:read src="resources/images/{2}.jpg" mime-type="image/jpeg"/>
+ <map:match pattern="**/skin/**.css">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="css/{2}.css"/>
+ <map:parameter name="mime-type" value="text/css"/>
+ </map:call>
</map:match>
- <map:match pattern="**images/*.gif">
- <map:read src="resources/images/{2}.gif" mime-type="image/gif"/>
+ <map:match pattern="**.css">
+ <map:read src="resources/css/{1}.css" mime-type="text/css"/>
+ </map:match>
+
+ <map:match pattern="skin/images/**.*">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="images/{1}.{2}"/>
+ <map:parameter name="mime-type" value="image/{2}"/>
+ </map:call>
</map:match>
- <map:handle-errors>
- <map:transform src="stylesheets/system/error2html.xsl"/>
- <map:serialize status-code="500"/>
- </map:handle-errors>
+ <map:match pattern="**/skin/images/**.*">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="images/{2}.{3}"/>
+ <map:parameter name="mime-type" value="image/{3}"/>
+ </map:call>
+ </map:match>
+
+ <map:match pattern="images/**.*">
+ <map:read src="resources/images/{1}.{2}" mime-type="image/{2}"/>
+ </map:match>
+ <map:match pattern="**/images/**.*">
+ <map:read src="resources/images/{2}.{3}" mime-type="image/{3}"/>
+ </map:match>
+
+
+ <map:match pattern="**favicon.ico">
+ <map:call resource="skin-read">
+ <map:parameter name="path" value="images/favicon.ico"/>
+ <map:parameter name="mime-type" value="application/ico"/>
+ </map:call>
+ </map:match>
+
</map:pipeline>
</map:pipelines>
</map:sitemap>
-
-<!-- end of file -->
1.6 +1 -1 jakarta-avalon/src/xdocs/developing/conclusion.xml
Index: conclusion.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/conclusion.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- conclusion.xml 31 Jan 2002 15:43:49 -0000 1.5
+++ conclusion.xml 30 May 2002 16:28:17 -0000 1.6
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
+ xml:base="context://content/xdocs/developing/">
<chapterinfo>
<authorgroup>
<xi:xinclude href="../authors/bloritsch.xml"/>
1.6 +1 -1 jakarta-avalon/src/xdocs/developing/decomposing.xml
Index: decomposing.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/decomposing.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- decomposing.xml 31 Jan 2002 15:43:49 -0000 1.5
+++ decomposing.xml 30 May 2002 16:28:17 -0000 1.6
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
+ xml:base="context://content/xdocs/developing/">
<chapterinfo>
<authorgroup>
<xi:xinclude href="../authors/bloritsch.xml"/>
1.14 +1 -1 jakarta-avalon/src/xdocs/developing/framework.xml
Index: framework.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/framework.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- framework.xml 28 Feb 2002 13:35:58 -0000 1.13
+++ framework.xml 30 May 2002 16:28:17 -0000 1.14
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
+ xml:base="context://content/xdocs/developing/">
<chapterinfo>
<authorgroup>
<xi:xinclude href="../authors/bloritsch.xml"/>
1.12 +1 -1 jakarta-avalon/src/xdocs/developing/implementing.xml
Index: implementing.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/implementing.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- implementing.xml 31 Jan 2002 15:43:49 -0000 1.11
+++ implementing.xml 30 May 2002 16:28:17 -0000 1.12
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
+ xml:base="context://content/xdocs/developing/">
<chapterinfo>
<authorgroup>
<xi:xinclude href="../authors/bloritsch.xml"/>
1.6 +1 -1 jakarta-avalon/src/xdocs/developing/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 31 Jan 2002 15:43:49 -0000 1.5
+++ index.xml 30 May 2002 16:28:17 -0000 1.6
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing">
+ xml:base="context://content/xdocs/developing/">
<title>Developing With Apache Avalon</title>
<subtitle>Apache Avalon Project</subtitle>
<bookinfo>
1.6 +1 -1 jakarta-avalon/src/xdocs/developing/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/introduction.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- introduction.xml 31 Jan 2002 15:43:49 -0000 1.5
+++ introduction.xml 30 May 2002 16:28:17 -0000 1.6
@@ -4,7 +4,7 @@
"./dtd/docbookx.dtd">
<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
+ xml:base="context://content/xdocs/developing/">
<chapterinfo>
<authorgroup>
<xi:xinclude href="../authors/bloritsch.xml"/>
1.2 +2 -204 jakarta-avalon/src/xdocs/developing/strategies.xml
Index: strategies.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon/src/xdocs/developing/strategies.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- strategies.xml 31 Jan 2002 15:43:49 -0000 1.1
+++ strategies.xml 30 May 2002 16:28:18 -0000 1.2
@@ -1,204 +1,2 @@
-<?xml version="1.0" standalone="no"?>
-
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
- "./dtd/docbookx.dtd">
-
-<chapter xmlns:xi="http://www.w3.org/2001/XInclude";
- xml:base="context://xdocs/developing/">
- <chapterinfo>
- <authorgroup>
- <xi:xinclude href="../authors/bloritsch.xml"/>
- </authorgroup>
- </chapterinfo>
- <title>It's a Stragedy!</title>
- <subtitle>
- Now that you have some background on Avalon, you need some
- helpful hints on how to make it work best for you. It's time
- to learn some useful strategies that help you avoid slow
- performance, and speed up development time.
- </subtitle>
- <para>
- No, it's not a typo. The title has a deliberate play on words
- that implies that incorrect strategies can end up in tragedy.
- While the word "tragedy" may be a bit strong, the thought
- process does have a ring of truth to it. In this chapter we
- attempt to give you helpful hints and tips to boost the
- performance of your code and your development team. We will
- break the discussion into logging strategies, development
- strategies, component strategies, testing strategies, and
- finally some notes on security strategies.
- </para>
- <section>
- <title>Logging Strategies</title>
- <para>
- Logging is a necessary function in any system. The problem
- arises when the logging is not implemented in an efficient
- manner. Before we get into the nuts and bolts of
- <emphasis>how</emphasis> to create an efficient logging
- implementation, we have to identify <emphasis>what</emphasis>
- logging efficiency is.
- </para>
- <para>
- In the spirit of the Separation of Concerns pattern, there
- are two problem domains to consider: log organization and log
- writing. Log organization is primarily concerned with how the
- log categories are organized, and how the log files are
- organized. Log writing has to do with the mechanics of
- writing log entries.
- </para>
- <section>
- <title>Log Organization</title>
- <para>
- The Avalon framework and team advocate a category based
- approach to organizing loggers as opposed to a class name
- based approach. There is a very good reason for this.
- First is that categorization allows you to put information
- of like kind in one location. Second, it allows you to
- turn on and off an entire category of log messages.
- </para>
- <para>
- The arguments for the class name based logging usually
- fall under these assumptions:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- There is an implicit match between a class and a
- category.
- </para>
- </listitem>
- <listitem>
- <para>
- It makes it easier to get debug information from
- a specific class if we are having problems with it.
- </para>
- </listitem>
- <listitem>
- <para>
- The configuration file can handle the actual mapping
- of classname to log file.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- While these arguments have their point, so does a strict
- category based logging approach:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- You can narrow your log messages farther than simple
- class granularity. This way you can get information
- from the part of the class that really needs it.
- </para>
- </listitem>
- <listitem>
- <para>
- More often than not, a group of classes make up a
- Component. In most cases, the Component is what you
- are really interested in--not the individual classes.
- </para>
- </listitem>
- <listitem>
- <para>
- It is easier to manage a configuration file with only
- a few categories that are bound to Component instances
- during runtime.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- While the comparison is far from exhaustive, it gives you
- enough of an idea of the mindsets behind the approaches.
- In the end, you have to come up with something that works
- for the person using the log messages. The more simple
- the approach the better.
- </para>
- <section>
- <title>Log File Organization</title>
- <para>
- For many systems, one log file will do. However, there are
- many cases to split out different categories of messages to
- different files. Examples include web servers and ftp
- servers.
- </para>
- <para>
- Most web servers will have two log files: an access log
- and an error log. The access log is used to track which
- client asked for what resource. The error log is used to
- track information to help the administrator or developer
- figure out what is going wrong.
- </para>
- <para>
- Sometimes there are certain log files that may only be
- useful for debugging--such as the log entries from the
- Component Containers and Component Managers. You want
- to ensure that they are functioning correctly, but when
- the system is stable, those log messages can hide other
- potential issues in the sheer volume of log messages.
- By putting all these messages in their own file, you can
- separate the log files by who is concerned with their
- contents.
- </para>
- </section>
- <section>
- <title>Log Category Organization</title>
- <para>
- I would argue that it is a mistake to use only one
- category for all logging. The reason is that you
- will inevitably need to turn on and off a whole class
- of messages. Another reason is that you will need
- at least one category for each log file you have.
- One effective approach is to separate your logging
- needs into roles and classifications.
- </para>
- <para>
- If you have already decomposed your system into Components,
- then you have one set of categories defined. I would
- use a shorthand name for the category names for simple
- reference (e.g. "resource" instead of
- "org.apache.avalon.excalibur.resource.ResourceManager").
- The simplified names can be used for a broad set of
- classes. Using the same example, the name "resource"
- implies the Resource class, its manager, and anything
- that is directly associated with the concept of a "resource".
- </para>
- <para>
- You can also use classifications as a specialization of
- the main role classification. For example, all ComponentManager
- code would have a category name of "component". This would
- allow you to have a Category manager for the aforementioned
- "resource" infrastructure. Typically classifications are
- sub-categories. In this case, the full name of the "component"
- category would be "resource.component". This means that
- we are referring to the "component" classification for the
- "resource" role.
- </para>
- <para>
- Most of your logging needs can be organized into this
- two dimensional cross-section of Role and Classification.
- Roles are best for main categories due to their logical
- separation. Typical classifications are "component",
- "security", and "pool". These same classifications can
- be used as standard sub-categories of the different roles.
- This way your log entries can have fine-grained control
- that is logically organized.
- </para>
- </section>
- </section>
- <section>
- <title>Log Writing</title>
- <para>
- The mechanics of log writing can vastly affect the performance
- of your code. For instance, if you concatenate several strings
- together in your log messages, the <trademark>Java</trademark>
- Virtual Machine converts the concatenation to a StringBuffer,
- and performs the expensive <method>toString</method> operation
- on the result. The <classname>Logger</classname> interface
- provides a mechanism to optimize away these conversions when
- they are not needed.
- </para>
- </section>
- </section>
-</chapter>
-
+<?xml version="1.0" standalone="no"?> <!DOCTYPE chapter PUBLIC
"-//OASIS//DTD DocBook XML V4.1//EN"
"./dtd/docbookx.dtd"> <chapter xmlns:xi="http://www.w3.org/2001/XInclude";
xml:base="context://content/xdocs/developing/"> <chapterinfo>
<authorgroup> <xi:xinclude href="../authors/bloritsch.xml"/>
</authorgroup> </chapterinfo> <title>It's a Stragedy!</title> <subtitle>
Now that you have some background on Avalon, you need some helpful hints
on how to make it work best for you. It's time to learn some useful
strategies that help you avoid slow performance, and speed up development
time. </subtitle> <para> No, it's not a typo. The title has a
deliberate play on words that implies that incorrect strategies can end up
in tragedy. While the word "tragedy" may be a bit strong, the thought
process does have a ring of truth to it. In this chapter we attempt to
give you helpful hints and tips to boost the performance of your code and
your development team. We will break the discussion into logging
strategies, development strategies, component strategies, testing
strategies, and finally some notes on security strategies. </para>
<section> <title>Logging Strategies</title> <para> Logging is a
necessary function in any system. The problem arises when the logging is
not implemented in an efficient manner. Before we get into the nuts and
bolts of <emphasis>how</emphasis> to create an efficient logging
implementation, we have to identify <emphasis>what</emphasis> logging
efficiency is. </para> <para> In the spirit of the Separation of
Concerns pattern, there are two problem domains to consider: log
organization and log writing. Log organization is primarily concerned
with how the log categories are organized, and how the log files are
organized. Log writing has to do with the mechanics of writing log
entries. </para> <section> <title>Log Organization</title>
<para> The Avalon framework and team advocate a category based
approach to organizing loggers as opposed to a class name based
approach. There is a very good reason for this. First is that
categorization allows you to put information of like kind in one
location. Second, it allows you to turn on and off an entire category
of log messages. </para> <para> The arguments for the class
name based logging usually fall under these assumptions: </para>
<itemizedlist> <listitem> <para> There is an
implicit match between a class and a category. </para>
</listitem> <listitem> <para> It makes it
easier to get debug information from a specific class if we are
having problems with it. </para> </listitem>
<listitem> <para> The configuration file can handle the
actual mapping of classname to log file. </para>
</listitem> </itemizedlist> <para> While these arguments
have their point, so does a strict category based logging approach:
</para> <itemizedlist> <listitem> <para>
You can narrow your log messages farther than simple class
granularity. This way you can get information from the part of the
class that really needs it. </para> </listitem>
<listitem> <para> More often than not, a group of classes
make up a Component. In most cases, the Component is what you
are really interested in--not the individual classes. </para>
</listitem> <listitem> <para> It is easier
to manage a configuration file with only a few categories that are
bound to Component instances during runti
+you can separate the log files by who is concerned with their
contents. </para> </section> <section>
<title>Log Category Organization</title> <para> I would argue
that it is a mistake to use only one category for all logging. The
reason is that you will inevitably need to turn on and off a whole
class of messages. Another reason is that you will need at
least one category for each log file you have. One effective approach
is to separate your logging needs into roles and classifications.
</para> <para> If you have already decomposed your system
into Components, then you have one set of categories defined. I
would use a shorthand name for the category names for simple
reference (e.g. "resource" instead of
"org.apache.avalon.excalibur.resource.ResourceManager"). The
simplified names can be used for a broad set of classes. Using the
same example, the name "resource" implies the Resource class, its
manager, and anything that is directly associated with the concept of
a "resource". </para> <para> You can also use
classifications as a specialization of the main role classification.
For example, all ComponentManager code would have a category name of
"component". This would allow you to have a Category manager for the
aforementioned "resource" infrastructure. Typically classifications
are sub-categories. In this case, the full name of the "component"
category would be "resource.component". This means that we
are referring to the "component" classification for the "resource"
role. </para> <para> Most of your logging needs can
be organized into this two dimensional cross-section of Role and
Classification. Roles are best for main categories due to their
logical separation. Typical classifications are "component",
"security", and "pool". These same classifications can be used as
standard sub-categories of the different roles. This way your log
entries can have fine-grained control that is logically organized.
</para> </section> </section> <section> <title>Log
Writing</title> <para> The mechanics of log writing can vastly
affect the performance of your code. For instance, if you concatenate
several strings together in your log messages, the
<trademark>Java</trademark> Virtual Machine converts the concatenation
to a StringBuffer, and performs the expensive <method>toString</method>
operation on the result. The <classname>Logger</classname> interface
provides a mechanism to optimize away these conversions when they
are not needed. </para> </section> </section> </chapter>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
