A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/1162.html
Document ID: 1162
Branch: main
Language: default
Name: Configuration (unchanged)
Document Type: Cocoon Document (unchanged)
Updated on: 10/6/06 10:19:10 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: 87 bytes (previous version: 12997 bytes)
Content diff:
<html>
<body>
--- <p>Cocoon is a framework consisting of many different components. All these
--- components are managed by a component container. Starting with Cocoon 2.2
this
--- container is the <a href="http://www.springframework.org";>Spring
framework</a>.
--- So the first step in setting up Cocoon is actually setting up the container
and
--- configuring the Cocoon components in the container.</p>
+++ <p>moved to a new <a href="daisy:1258">location</a></p>
--- <p class="note">In previous versions of Cocoon, the container was setup by
--- Cocoon itself which created a strong dependency between the container and
Cocoon
--- and made integrating Cocoon with other frameworks very difficult.</p>
---
--- <p class="note">You can get a skeleton Cocoon application by using the
Cocoon
--- archetypes for Maven 2 - so you don't need to do most of the stuff described
--- here by hand.</p>
---
--- <p>There are various ways to setup a Spring container (have a look at the
Spring
--- documentation), but we suggest to setup a Spring application context using
the
--- context loader listener in your web.xml:</p>
---
--- <p><strong>TBD: Show snipped from web.xml</strong></p>
---
--- <p>This context listener is invoked by the servlet container on startup of
your
--- web application. By default the configuration for the application context is
--- read from the file "WEB-INF/applicationContext.xml". This is the place to
--- configure the Cocoon components:</p>
---
--- <p><strong>TBD: Show snipped from applicationContext.xml and explain
it</strong>
--- </p>
---
--- <p>The main goal for the new Cocoon 2.2 configuration system is to avoid
--- patching of any provided configuration file (If you're familiar with
previous
--- 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>
