config-bootstrapper

Helps managing application and logging configuration for different environments in Servlet based Java applications.

Features

* Possibility to have separate application config files per environment * Possibility to have separate log4j config files per environment * Reloads log4j configuration automatically on configuration changes, when read from file system * Uses configuration files on classpath by default (i.e. no need for explicitly stating config files during development) * Possiblity to set additional system properties from application configuration file

Maven dependency

Add the following dependency to your pom.xml to get the latest version from Maven Central Repo.

	<dependency>
		<groupId>com.chilmers.config-bootstrapper</groupId>
		<artifactId>config-bootstrapper</artifactId>
		<version>1.3</version>
	</dependency>

Quick start

A more comprehensive usage guide is found further down.

Add this to your web.xml before any other listeners that need to use the configuration or that needs to log.

  <listener>
      <listener-class>com.chilmers.configbootstrapper.ConfigServletContextListener</listener-class>
  </listener>

You can now use the system property "application.config.location" to read your config location, for example to inject your config in Spring.

  <context:property-placeholder location="${application.config.location}"/>

Or use readApplicationConfiguration in ConfigHelper:

  See ConfigHelper.readApplicationConfiguration()

The application will now read application.properties from the classpath, if you need to read from another location you might specify this with a system property (or environment variable or servlet context parameter) at startup.

For example:

 mvn jetty:run -Dapplication.config.location=file:/Users/chilmers/myApp/app-config.properties

or if you want to read config from classpath (other than application.properties)

 mvn jetty:run -Dapplication.config.location=classpath:app-config.properties

At this stage the application will try to find a default log4j configuration file i.e. log4j.xml or log4j.properties on the classpath If you need to change this, add an entry like this to your application configuration file:

  application.log4j.config.location=file:/Users/chilmers/myApp/app-log4j.xml

or if you want to read logging config from the classpath (other than log4j.xml/log4j.properties)

  application.log4j.config.location=classpath:app-log4j.xml

Main functionalities

• Determines which configuration file to use
  Looks in the given order in system properties, environment variables, and servlet context parameters for the location of a properties file to use for configuration.
  By default it looks for an entry named "application.config.location".
  If no such entry was found the location defaults to classpath:application.properties
  The location that was determined will be written to the system property (by default "application.config.location").
  The obvious benefit of doing this is in when no location has been specified, you will still be able to read the configuration location from this system property. In other environments where you want to add a configuration on the file system, you can do this and add the location as a system property, environment variable or servlet context parameter and still read the location from the system property.
  This makes it easy to use separate configurations for separate environments. Use classpath: for files on the classpath and file: to read from an external location.
• Loads logging (log4J) configuration
  Uses the given application configuration to specify a location of a log4j configuration file. By default it looks for an entry named "application.log4j.config.location" in the application configuration.
  In this way it is easy to provide different logging configurations for different environments.
  If no specific log4j-configuration is configured, it falls back to log4j's default configuration handling (e.g. log4j.xml or log4j.properties on the classpath)
  
• Possibility to set system properties from application configuration
  Entries in the configuration file starting with "system.property." will automatically be written to the system properties.
  Example:
  

  system.property.foo=bar

  Will write foo=bar as a system property, which is handy in some circumstances.
  Don't use this feature if you don't understand what it is, since it might clutter your system properties.
  

Finding correct application configuration

This context listener will in the given order look in the system properties, environment variables
or the servlet context parameters for the location of a configuration file to use in the application.
By default it will look for an entry with the key "application.config.location". (This key name can be overridden, see Overriding defaults below)
If no such entry is found it will by default fall back to using "classpath:application.properties" as configuration location. (The fallback location can also be overridden if necessary, see below)

Whichever configuration location string is decided, will be set in the system properties using the same key as above, i.e by default it will be set in system property "application.config.location"
This makes it possible to locate the configuration from within the application, for example by reading it into a PropertyResourceBundle or by using Spring's PropertyPlaceholderConfigurer like this:

<bean id="placeholderConfig" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
      <property name="location" value="${application.config.location}" />
</bean>

Or, if you have the context namespace defined, simply:

<context:property-placeholder location="${application.config.location}"/>

Or use readApplicationConfiguration in ConfigHelper for non-Spring applications:
See ConfigHelper.readApplicationConfiguration()

Logging configuration (i.e. Log4j)

This mechanism configures Log4j using a given file whose location is stated in the application configuration, or if no such file is available falls back to Log4j's default configuration behavior,
i.e. looks for log4j.xml or log4j.properties on the classpath.
Use this format classpath:my-log4j-config.xml to point out a file on the classpath.
If you want to point out a file on the file system you can either prefix with file: or just write the location as it is.
To use an external log4j file you will have to state the location of the file in the application configuration as a property with the key given by "application.log4j.config.location". (This key name can be overriden, see Overriding defaults below)

Usage

Add this to your web.xml and make sure it is located before any application specific listeners that need to use the configuration location property or that needs to log. E.g. before Spring's ContextLoaderListener

<listener>
	<listener-class>com.chilmers.configbootstrapper.ConfigServletContextListener</listener-class>
</listener>

If you want to specify an external configuration file (instead of the default "classpath:application.properties"),
add a context-param or more likely a system property or environment variable stating the location of your application configuration.
For example:

As context param:

<context-param>
      <description>The location of the application configuration. 
          If not set it defaults to classpath:application.properties</description>
      <param-name>application.config.location</param-name>
      <param-value>file:/Users/myusername/my-app-config/app.properties</param-value>
</context-param>

As environment variable in a bash shell:

export application.config.location=file:/Users/myusername/my-app-config/app.properties

As a system property upon starting your container:

java [your application] -Dapplication.config.location=file:/Users/myusername/my-app-config/app.properties

Overriding defaults

The following context-parameters can be set to configure the listener.
All of them have default values so they don't have to be set if not needed

<context-param>
      <description>Sets the key for the entry that holds the application configuration location. 
          If not set it defaults to application.config.location</description>
      <param-name>configServletContextListener.configLocationPropertyKey</param-name>
      <param-value>myown.config.location</param-value>
</context-param>

<context-param>
      <description>Sets the key for where in the application configuration file to look for a log4j
          configuration file location.
          If not set it defaults to application.log4j.config.location</description>
      <param-name>configServletContextListener.log4jConfigLocationPropertyKey</param-name>
      <param-value>myown.log4j.config.location</param-value>
</context-param>

<context-param>
      <description>Sets the location of the application configuration to fall back to if no other configuration
          file location was set. E.g. a bundled configuration on the classpath. 
          If not set it defaults to classpath:application.properties</description>
      <param-name>configServletContextListener.fallbackConfigLocation</param-name>
      <param-value>classpath:myown.properties</param-value>
</context-param>

<context-param>
      <description>
      Application name that is printed when using System.out logging when no logging manager is available.
      Defaults to the display-name of the web.xml or if no display-name exists it will be ConfigServletContextListener
      </description>
      <param-name>configServletContextListener.applicationName</param-name>
      <param-value>My Application</param-value>
</context-param>

License

Config-bootsrapper is licensed under LGPL 2.1 as described in the LICENSE file.

Javadoc

Link to API documentation (javadoc)