Versions Compared

Old Version 29

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version 30

changes.mady.by.user Mark H. Wood

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Picky language fixes

...

  • Apache Commons Configuration is a well-established Java library whose goal is to make configuration more flexible and easier to manage.
  • It automatically interpolates all settings at runtime. This means we no longer need to replace variables (${setting}) within our configurations. They will be auto-determined at runtime based on the value of that variable within one of the configuration files For more on variable interpolation see its Basic Features documentation
  • It is a flexible configuration scheme. It can read configurations from several sources at once, including Properties files, XML config files and even database tables (see its Overview documentation).  Currently, in the DSpace Enhanced Configuration Scheme we are still only using Properties files, similar to DSpace 5 and below. But, we now be are able to easily move all or some configurations to XML configs or database config tables.
    • The locations of the configuration sources can be easily customized by DSpace administrators in a new config-definition.xml file, which configures Apache Commons Configuration for DSpace. More on that below.
    • The config-definition.xml file itself is simply a "configuration definition" file as defined by Apache Commons Configuration. See the Configuration File Documentation for more details.
  • It allows for easy overriding of configuration values from other sources. How the overrides occur is up to how you've configured Apache Commons Configuration.  For DSpace, we have a new config-definition.xml which defines the following override scheme (again, this can be easily tweaked for local needs):
    • If a setting is specified in Java System Properties (e.g. -D[setting]=[value]), it overrides the same setting found in any below location
    • If a setting is specified as an Environment Variable, it overrides the same setting found in any below location
    • If a setting is specified in the new local.cfg configuration file, it overrides the default value in any below location
    • Default values for all settings are specified in the dspace.cfg and the modules/*.cfg configuration files.
  • It supports enhanced Properties files.  This means our dspace.cfg , local.cfg and other configuration files can now immediately support some enhanced options, including:
    • The ability to easily include other configuration files via: "include=[config-file-location]"  (See the end of the updated dspace.cfg for examples)
    • The ability to provide lists of values to "array" configurations by specifying the setting multiple times (rather than creating a giant comma separated configuration spanning multiple lines). For example, enabling both LDAP and Password authentication can now be done via these two lines:
      • plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.LDAPAuthentication
      • plugin.sequence.org.dspace.authenticate.AuthenticationMethod = org.dspace.authenticate.PasswordAuthentication
    • For more information see the Commons Config Properties File documentation
  • More information/ features can also be found in the Apache Commons Configuration v1.10 User Guide

...

  • All DSpace configurations are loaded via Properties files
    • Note: Apache Commons Configuration does support other configuration sources such as XML configurations or database configurations, see .  See its Overview documentation.)
  • Configuration Files/Sources: By default, only two configuration files are loaded into Apache Commons Configuration:
    • local.cfg (see documentation on local.cfg above.)
    • dspace.cfg (NOTE: however that all modules/*.cfg are loaded by dspace.cfg via "include=" statements at the end of that configuration file.)
  • 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 each minute for changes. If they have changed, they are automatically reloaded.

...

  1. Change your config-definition.xml to use a system property (of your choice) instead of the hardcoded name "local.cfg".  The Configuration Definition file itself does allow for variables to be included, but they must be specified in a previous configuration source (in that config-definition.xml) or via a system property. See the Configuration File Documentation for more details.  So, you could simply change your config-definition.xml to use a "dspace.env" system property, and pass "-Ddspace.env=dev" to have it use a [dspace.dir]/config/dev.cfg:

    Code Block
    <!-- Change local.cfg to be ${dspace.env} in your config-definition.xml -->
<properties fileName="${dspace.env}.cfg" throwExceptionOnMissing="false" config-name="local" config-optional="true">
...
</properties>

<!-- OPTIONALLY: If you wanted to have some default local configs shared among *all* environments, you could add
     a NEW "properties" file to always load those defaults. In this example, default.cfg would be loaded for ALL 
     environments. Configs in the environment-specific ${dspace.env}.cfg would override default.cfg, and
     both would override dspace.cfg (and other *.cfg). -->
<properties fileName="default.cfg" throwExceptionOnMissing="false" config-name="default" config-optional="true">
...
</properties>

  2. Alternatively, you could use the "include=" option (of Apache Commons Configuration Properties Files) within your local.cfg file to load a different configuration file, again based on a setting specified as a system property. For example, your local.cfg file would ONLY consist of "include=" statement(s), which would load whichever configuration file was specified as the "dspace.env" system property:

    Code Block
    # This is the ENTIRE local.cfg -- (all settings would instead be located in environment-specific config files).
# Its job is just to load up the configuration for the environment specified by "dspace.env"
# For example, -Ddspace.env=dev would load [dspace.dir]/config/dev.cfg
#         and  -Ddspace.env=prod would load [dspace.dir]/config/prod.cfg

# Load the environment-specific file
include = ${dspace.env}.cfg

# OPTIONALLY: If you wanted to have some default local configs shared among *all* environments, you could add 
# a second "include=" statement to always load those defaults from a file of your choice. In this example, 
# a default.cfg would be loaded for ALL environments. Configs in the environment-specific ${dspace.env}.cfg 
# would override default.cfg, and both would override dspace.cfg (and other *.cfg).
include = default.cfg

...