Reloading of configuration files

EasyConf supports automatic reloading of configuration files when they change in a very efficient way. Many people wish they could make changes to the configuration of an application without having to restart it, but this is usually discarded for performance reasons (at least for applications which are on production servers). EasyConf now offers easy access to this functionality without any significant performance delay.

This functionality comes disabled by default and can be activated either for one component or for all of them. The activation is done through a special property called easyconf:reload-delay. This property sets how often (in seconds) EasyConf should check if a file has changed.

To configure a component called my-app so that it is reloaded when it changes edit the file my-app.properties (or any of the files it includes) and add the following property: 

               easyconf:reload-delay=5
By adding this line EasyConf will check every 5 seconds (at most) if the file has changed. If so it will reload its contents. Note that the actual check will be done lazyly, only when a method to retrieve a property or the component configuration is called. Until one of these methods is not called EasyConf will not check if the file has changed (no matter how much time passes). In other words this means that no extra threads are used as they could cause problems in some environments.

It is also possible activate and control the automatic reloading by setting this property in global-configuration.properties (or any of the files it includes). If the property is set in this file it will be applied to all of the components.

Changes in XML files are also automatically reloaded when a reload delay is provided. The reload delay is provided as explained in the previous paragraphs. So to automatically reload the file my-app.xml it will be necesary to set the easyconf:reload-delay property in the file my-app.properties (or any of the files it includes) or global-configuration.properties (or any of the files it includes)

Limitations

Automatic reloading is performed file by file, so new files will not be detected. If an existent file is modified to include a new file from it using the include-and-override property the new file won't be loaded either.

In order to determine if the file has changed EasyConf needs to know its path on the filesystem. When the files are loaded from the classpath it is up to the classloader to offer a URL which contains the filesystem path or not. EasyConf is able to obtain the path if the protocol used by the classloader is file or jar. Some classloaders are known to use the classloader protocol and in this case EasyConf won't have enough information to reload the file. This issue is of importance mainly when configuring J2EE applications. For example, the classloader used by JBoss offers enough information and reloading works, but the one used by Oracle10g doesn't. If you have information about other app. servers please let us know and we'll update this information.

To overcome these limitations you can use the manual refreshing service. This service is offered through the method EasyConf.refreshComponent(componentName) and is also available to J2EE applications as a Servlet or Struts Action.

How does it work?

EasyConf leverages the infrastructure provided by Jakarta Commons Configurations. Each file read is attached a ReloadingStrategy. Each time the getProperty() method (or any of its typed equivalents) is called the strategy is asked if the configuration has changed. The first time the strategy will query the file system for the date when the file was last changed. If it is newer than the last time the file was loaded then it is reloaded. The strategy keeps track of two timestamps:

  • lastChecked: the last time that the last modification time of the file was retrieved from the file system
  • lastModified: the last time the file was loaded
Each time the strategy is asked if the file has changed it compares the lastChecked timestamp plus the reload delay to the current time (calculated as System.currentTimeMillis()). If the current time is bigger then the last modification time of a file is retrieved. If it is bigger than the lastModified timestamp then it will be reloaded.

Note that EasyConf has its own ReloadingStrategy as there are some performance issues with the version that comes with Commons configurations. A fix has already been sent to them so that in future versions we will be able to use it.

To implement the reloading of XML files, when a configuration object is built using digester it is stored in a wrapper along with a specific ReloadingStrategy. This strategy works in the same way as has been explained for properties files.