[DAISY] Updated: Overview

[da...@cocoon.zones.apache.org]

A document has been updated:

http://cocoon.zones.apache.org/daisy/documentation/1162.html

Document ID: 1162
Branch: main
Language: default
Name: Overview (previously Configuration)
Document Type: Cocoon Document (unchanged)
Updated on: 10/6/06 9:59:44 AM
Updated by: Reinhard Pötz

A new version has been created, state: publish

Parts
=====

Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 1691 bytes (previous version: 12997 bytes)
Content diff:
(33 equal lines skipped)
    versions of Cocoon you might remember the patching of the cocoon.xconf or
    web.xml to satisfy your project needs.)</p>
    
--- <h1>Property Configuration</h1>
--- 
--- <p>Cocoon comes with a smart configuration mechanism based on property files.
--- The configuration of Cocoon (or more precisely of the components) is based on
--- XML files for the various components. To customize these configuration files
--- without changing the files itself you can define properties to which you can
--- refer to from within the configuration files (and sitemaps).</p>
--- 
--- <p>You can define as many property files and define your own properties as you
--- want. Store them in the "WEB-INF/cocoon/properties" directory and Cocoon will
--- read all of them on startup in alphabetical order. If two files provide values
--- for the same property, the last definition wins. Please note that any changes
--- you make to the property files will not be reflected during runtime. The changes
--- will take effect, the next time you startup the Cocoon web application (or
--- restart the servlet context).</p>
--- 
--- <p>You can refer to the values of a property by using the common
--- ${PROPERTY_NAME} syntax in your configuration file or sitemap (this includes
--- spring configuration files loaded by Cocoon as well).</p>
--- 
--- <h2>Running modes</h2>
--- 
--- <p>Cocoon extends the property based configuration mechanism by "running
--- modes". You define a running mode when you start Cocoon (default is "prod"). The
--- name of the running mode is used to read additional property files on startup.
--- Cocoon reads first all property files from "WEB-INF/cocoon/properties" and after
--- that from "WEB-INF/cocoon/properties/${RUNNING_MODE}".</p>
--- 
--- <p>For example if you have different database connections during development and
--- in production, just put a properties file containing the connection information
--- for development in the "WEB-INF/cocoon/properties/dev" directory and put another
--- property file with the production settings in "WEB-INF/cocoon/properties/prod".
--- (Of course think about security issues regarding this information - you might
--- not want that a developer knows the database configuration of the production
--- machine).</p>
--- 
--- <p>You can easily set the running mode by setting the system property
--- "org.apache.cocoon.mode" on startup of Cocoon, for example:<br/>
--- "-Dorg.apache.cocoon.mode=dev" or by specifying the mode in your
--- "applicationContext.xml" (see above). The system property takes precedence over
--- the application context configuration.</p>
--- 
--- <p>Currently Cocoon supports three predefined running modes. You can choose
--- between "dev", "test" and "prod" or use your own mode.</p>
--- 
--- <h2>Properties and Sitemaps</h2>
--- 
--- <p>As explained above, you can simply refer to a value of a property within a
--- sitemap. In addition a sitemap can have a set of own properties which are only
--- available to this sitemap (and the components defined in this sitemap) and all
--- sub sitemaps. This mechanism is a replacement for the deprecated global
--- variables.</p>
--- 
--- <p>By default each sitemap tries to read properties from within the directory
--- the sitemap is in, looking into these two directories: "config/properties" and
--- "config/properties/${RUNNING_MODE}. If you don't want to use these default
--- locations, you can specify the attribute "use-default-include" with a value of
--- "false" at the map:components element in the sitemap.</p>
--- 
--- <p>You can specify your own property directory where all property files are read
--- from by using the element "map:include-properties" with the attribute "dir"
--- specifying the directory location inside the map:components element in the
--- sitemap.</p>
--- 
--- <p>If you don't want that Cocoon tries to replace strings containing a property
--- reference in your sitemap, you can set the attribute "replace-properties" with
--- the value "false" at the map:components element in the sitemap.</p>
--- 
--- <p>Please note, that you can't use properties to define the values for the
--- attributes on the map:components element. This means that the possible values
--- for "use-default-include" and "replace-properties" are hard-coded values which
--- can't be changed using properties.</p>
--- 
--- <h2>Properties and Java Code</h2>
--- 
--- <p>If you need access to the defined properties within your Java code, just
--- lookup the Settings bean. This bean provides access to all available properties.
--- </p>
--- 
--- <h2>Using your own Property Provider</h2>
--- 
--- <p>If you want to store all your properties in a different storage than the file
--- system, for example in a database, you can implement your own provider
--- mechanism. Add a bean implementing the PropertyProvider interface to the root
--- application context of Spring and Cocoon will get all properties from this
--- provider after it has read the properties from the properties files.</p>
--- 
--- <h2>User defined Properties</h2>
--- 
--- <p>If the user who has started the web application has a "settings.properties"
--- file stored in the ".cocoon" directory in his home directory, these properties
--- will be read and applied as well.</p>
--- 
--- <h2>Additional Property File</h2>
--- 
--- <p>After all property files have been read, the value of the property
--- "org.apache.cocoon.settings" is evaluated. If this property is set, the property
--- file defined by this value is read and applied as well. The property could have
--- been set by any previously read property file or by a system property.</p>
--- 
--- <h2>Summarizing Property Loading on Startup</h2>
--- 
--- <p>The whole property mechanism is performed before the Cocoon component
--- container is setup and consists of the following seven steps:</p>
--- 
--- <ol>
--- <li>WEB-INF/cocoon/properties/*.properties</li>
--- <li>WEB-INF/cocoon/properties/[RUNNING_MODE]/*.properties</li>
--- <li>Custom PropertyProvider defined in the Spring root application context</li>
--- <li>Properties set by the servlet environment</li>
--- <li>[USER_HOME]/.cocoon/settings.properties</li>
--- <li>Additional property file specified by "org.apache.cocoon.settings" property
--- </li>
--- <li>System properties</li>
--- </ol>
--- 
--- <p>The different property files and providers are queried in this order and the
--- files in a directory are processed in alphabetical order. The properties are
--- merged into one big set of properties. If there is more than one definition for
--- a property the last definition wins.</p>
--- 
--- <h1>Logging</h1>
--- 
--- <p>Cocoon uses <a href="http://logging.apache.org/log4j">Log4J</a> by default
--- and all log statements are written to a single log file in the temporary
--- directory of the application server. The configuration for log4j is in the
--- WEB-INF directory in the log4j.xconf file. The logging can be controlled in
--- various ways as described below.</p>
--- 
--- <h2>Location of the logging configuration</h2>
--- 
--- <p>By default, Cocoon loads <em>WEB-INF/log4j.xconf</em> as the configuration
--- for Log4J. If you want to make any changes to the configuration file, it is
--- advisable to not alter this default file but instead use your own configuration.
--- By setting the <em>org.apache.cocoon.logging.configuration</em> property in your
--- properties, you can point to a different configuration file.</p>
--- 
--- <h2>Bootstrap log level</h2>
--- 
--- <p>TBD</p>
--- 
--- <h2>Environment Logging Category</h2>
--- 
--- <p>TBD</p>
--- 
--- <h2>Cocoon Logging Category</h2>
--- 
--- <p>TBD</p>
--- 
--- <h2>Overriding the log level</h2>
--- 
--- <p>For development you can override the configured log level from your Log4J
--- configuration by setting the property
--- <em>org.apache.cocoon.override.loglevel</em> with the name of the level. This is
--- for example very usefull to set the log level to debug for development purposes
--- without changing the logging configuration.</p>
--- 
--- <h2>Shielded Classloading</h2>
--- 
--- <p>By default, Cocoon is configured to use shielded classloading. Therefore an
--- own instance of Log4J is instantiated for just the Cocoon web application. If
--- you want to share a global Log4J configuration between web applications, you
--- have to turn off the shielded classloading for the whole Cocoon instance of for
--- just Log4J.</p>
--- 
--- <h2>Using your own logging system</h2>
--- 
--- <p>If you want to use your own logging system instead of Log4J you can setup a
--- Logger bean in the root application context of Spring. This bean must be
--- registered with the name <em>org.apache.avalon.framework.logger.Logger</em> and
--- it must conform to the interface with this name.</p>
--- 
--- <h1>Component Configurations</h1>
--- 
--- <p>While older versions of Cocoon used one single big file for the configuration
--- of components (the cocoon.xconf), the later versions support to split this
--- configuration file into several files using an include mechanism. You can refer
--- to properties from within your configuration files and Cocoon will replace these
--- accordingly.</p>
--- 
--- <h2>Spring Configuration</h2>
--- 
--- <p>You can just drop in your Spring bean configuration files into
--- "WEB-INF/spring" and these files are applied automatically.</p>
--- 
--- <h2>Legacy Configuration</h2>
--- 
--- <p>The main part of Cocoon is configured by using the Avalon configuration file
--- format. By default all configuration files ending with ".xconf" which are
--- contained in the WEB-INF/xconf directory are included by default. So, you can
--- just add your own configuration files there and they are included automatically.
--- </p>
--- 
--- <h2>Sitemap Configuration</h2>
--- 
--- <p>You can use per sitemap components using includes as well. By default all
--- Avalon based configuration files from "config/xconf" and all Spring bean
--- configuration files from "config/spring" are included.</p>
--- 
--- <h1>Shielded Classloading</h1>
--- 
--- <p>Shielded classloading is an optional feature of Cocoon which helps you in
--- avoiding typical problems with respect to class loading. Usually the servlet
--- container sets up a class loader for each web application. This class loader
--- works "parent-first" which means that whenever a class is loaded it is first
--- searched in the parent class loader of the web application class loader and only
--- if its not available there, it is loaded from the classes in WEB-INF/classes or
--- the jars in WEB-INF/lib. In general this is a useful mechanism which also allows
--- you to share classes between web applications by putting them in the parent
--- class loader (refer to the documentation of your application server/servlet
--- engine for more information).</p>
--- 
--- <p>Unfortunately there are some problems with this approach: for example if the
--- servlet engine has configured a logging framework like commons logging and
--- exposes this  in the parent class loader for the web applications, than all web
--- applications have to use this configuration and are not able to use their own.
--- Even more important is the used XSLT processor (and some other stuff contained
--- in the endorsed directory). By default you always use the XSLT processor shipped
--- with the JDK; you can override this by specifying one using the endorsed
--- mechanism but in many cases you can't use this way. As the XSLT processor
--- shipped with the JDK has some bugs it is advisable to use the latest version.
--- </p>
--- 
--- <p>The only reliable way of avoiding all these class loading issues is to use a
--- mechanism we call shielded class loading: the web application uses its own class
--- loader which works "parent-last". In this case classes are always tried to be
--- loaded from the WEB-INF/classes or WEB-INF/lib directory first. Through this
--- mechanism you can enforce the use of the XSLT processor you want for your
--- application, of the logging configuration you need etc.</p>
--- 
--- <p>Some application servers provide a configuration for this, but you can also
--- use some of the functionality provided by Cocoon: if you are using the Cocoon
--- deploy plugin with Maven 2, this plugin rewrites your web.xml to use the
--- shielded class loader.</p>
--- 
    </body>
    </html>


Collections
===========
Removed from collection: documentation