Versions Compared

Old Version 22

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 23

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: initial docs on configuration scheme / config-definition.xml

...

All DSpace *.cfg files use the Apache Commons Configuration properties file syntax.  This syntax is very similar to a standard Java properties file, with a few notable enhancements described below.

...

Additional examples of escaping special characters are provided in the documentation of the Apache Commons Configuration properties file syntax.

Specifying Multiple Values for Properties

Because DSpace supports the Apache Commons Configuration properties file syntax, it is much easier to specify multiple values for a single setting. All you have to do is repeat the same property name multiple times in the same *.cfg file.

...

Additional examples of creating lists or arrays of values are provided in the documentation of the Apache Commons Configuration properties file syntax.

Including other Property Files

Because DSpace supports the Apache Commons Configuration properties file syntax, it also can include/embed property files within other property files by using the "include=" setting.

...

This ability to include other files is also possible with the local.cfg file, should you want to subdivide your localized settings into several locally specific configuration files.

Configuration Scheme for Reloading and Overriding

Note

In DSpace 6.0, while the DSpace API supports dynamically reloading configurations, the user interfaces (e.g. XMLUI and JSPUI) still cache some configuration settings.  This means that while the API layer may reload a new value, that new value may not always affect/change the behavior of your user interface (until you restart Tomcat). This is something we are working to correct in future versions of DSpace.

Because DSpace supports the Apache Commons Configuration, its configurations can now be reloaded without restarting your servlet container (e.g. Tomcat). By default, DSpace checks for changes to any of its runtime configuration files every 5 seconds. If a change has been made, the configuration file is reloaded. The 5 second interval is configurable in the config-definition.xml (which defines the configuration scheme DSpace uses).

Additionally, DSpace provides the ability to easily override default configuration settings (in dspace.cfg or modules/*.cfg) using a local.cfg file (see __ ) or using System Properties / Environment Varilables.

Both of these features are defined in DSpace's default "configuration scheme" or "configuration definition" in the [dspace]/config/config-definition.xml file. This file defines the Apache Commons Configuration settings that DSpace utilizes by default. It is a valid "configuration definition" file as defined by Apache Commons Configuration. See their Configuration Definition File Documentation for more details.

You are welcome to customize the config-definition.xml to customize your local configuration scheme as you see fit.  Any customizations to this file will require restarting your servlet container (e.g. Tomcat).

By default, the DSpace config-definition.xml file defines the following configuration scheme:

  • Configuration File Syntax/Sources: All DSpace configurations are loaded via Properties files (using the Configuration File Syntax detailed above)
    • Note: Apache Commons Configuration does support other configuration sources such as XML configurations or database configurations (see its Overview documentation).  At this time, DSpace does not utilize these other sorts of configurations by default. However, it would be possible to customize your local config-definition.xml to load settings from other locations.
  • Configuration Files/Sources: By default, only two configuration files are loaded into Apache Commons Configuration for DSpace:
    • local.cfg (see The local.cfg Configuration Properties File documentation below)
    • dspace.cfg (NOTE: all modules/*.cfg are loaded by dspace.cfg via "include=" statements at the end of that configuration file. They are essentially treated as sub-configs which are embedded/included into the dspace.cfg)
  • Configuration Override Scheme: The configuration override scheme is defined as follows. Configurations specified in earlier locations will automatically override any later values:
    • System Properties (-D[setting]=[value]) override all other options
    • Environment Variables
    • local.cfg
    • dspace.cfg (and all modules/*.cfg files) contain the default values for all settings.
  • Configuration Auto-Reload: By default, all configuration files are automatically checked every 5 seconds for changes. If they have changed, they are automatically reloaded.

For more information on customizing our default config-definition.xml file, see the Apache Commons Configuration documentation on the configuration definition file. Internally, DSpace simply uses the DefaultConfigurationBuilder class provided by Apache Commons Configuration to initialize our configuration scheme (and load all configuration files).

Why are there multiple copies of some config files?

...

Many configuration names/keys have changed!

 

If you are upgrading from an earlier version of DSpace, you will need to be aware that many configuration names/keys have changed. Because Apache Commons Configuration allows for auto-overriding of configurations, all configuration names/keys in different *.cfg files MUST be uniquely named (otherwise accidental, unintended overriding may occur).

In order to compensate for this, all modules/*.cfg files had their configurations renamed to be prepended with the module name.  As a basic example, all the configuration settings within the modules/oai.cfg configuration now start with "oai.".

Additionally, while the local.cfg may look similar to the old build.properties, many of its configurations have slightly different names. So, simply copying your build.properties into a local.cfg will NOT work.

This means that DSpace 5.x (or below) configurations are NOT compatible with the Enhanced Configuration Scheme.  While you obviously can use your old configurations as a reference, you will need to start with fresh copy of all configuration files, and reapply any necessary configuration changes (this has always been the recommended procedure). However, as you'll see in the next section, you'll likely want to do that anyways in order to take full advantage of the new local.cfg file.

[dspace]/config/config-definition.xml