A new document has been created.
http://cocoon.zones.apache.org/daisy/documentation/1261.html
Document ID: 1261
Branch: main
Language: default
Name: Property Configuration
Document Type: Cocoon Document
Created: 10/6/06 10:14:09 AM
Creator (owner): Reinhard Pötz
State: publish
Parts
=====
Content
-------
Mime type: text/xml
Size: 6018 bytes
Content:
<html>
<body>
<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>
<h1>Running modes</h1>
<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>
<h1>Properties and Sitemaps</h1>
<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>
<h1>Properties and Java Code</h1>
<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>
<h1>Using your own Property Provider</h1>
<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>
<h1>User defined Properties</h1>
<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>
<h1>Additional Property File</h1>
<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>
<h1>Summarizing Property Loading on Startup</h1>
<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>
</body>
</html>
Collections
===========
The document belongs to the following collections: cdocs-core
