A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/1162.html
Document ID: 1162
Branch: main
Language: default
Name: Configuration (previously Overview)
Document Type: Cocoon Document (unchanged)
Updated on: 10/6/06 10:00:37 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: 12997 bytes (previous version: 1691 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>
