Skip to content

Users Guide

Jump to bottom
allenxwang edited this page Jun 7, 2012 · 77 revisions

Getting started

Use a file on local file system as the configuration source

There are two ways to get Archaius working out of the box using a local configuration file to feed dynamic properties to your application.

  • By default, Archaius will look for a file named “config.properties” on the application’s classpath and read its content as configuration properties
  • You can define a system property “configurationSource.additionalUrls” that contains the URL path to a local configuration file. For example, add this to your application start up script
-DconfigurationSource.additionalUrls=file:///apps/myapp/application.properties

Assume there is a property “lock.waitTime” in the configuration file and can be changed dynamically at runtime. Here is the code you can use in your application to utilize the dynamic nature of this property with Archaius:

  // create a property whose value is type long and use 1000 as the default 
  // if the property is not defined
  DynamicLongProperty timeToWait = 
      DynamicPropertyFactory.getInstance().createLongProperty("lock.waitTime", 1000);
  // ...
  ReentrantLock lock = ...;
  // ...
  lock.tryLock(timeToWait.get(), TimeUnit.MILLISECONDS); // timeToWait.get() returns up-to-date value of the property

There are two things to note in the above code:

  1. timeToWait is a property that is bound to a long value. There is no code needed to parse string to long.
  2. In the call to lock.tryLock(), instead of using a predefined long parameter, we used timeToWait.get() to get the value that could be potentially changed at runtime

Now if you need to change the value of “lock.waitTime”, simply edit the configuration file and change the value of the property. By default, Archaius will read the file every minute and this change will be effective within a minute in your application.

Use multiple URLs as configuration source

You can define multiple URLs delimited by comma “,” for the system property “configurationSource.additionalUrls”, in addition to the default “config.properties” file on classpath. Archaius will read “config.properties” first, then all the other URLs defined in the system property in the order it is defined. If there are two URLs that contains the same property, the final value will be from the one that gets read later.

For example, you can deploy your application with set of default properties in file config.properties and provide another set of properties as overrides in another URL.

Assume you define this in config.properties

lock.waitTime=200

and use this http URL to provide overriding properties

-DconfigurationSource.additionalUrls=http://myserver/properties

Also the content of http://myserver/properties contains this line

lock.waitTime=500

Using the same code in the previous example, the final value of lock.waitTime in your application will be 500 instead of 200. This use case is particularly helpful if your application is running in a cluster. By defining an additional configuration URL as a centralized HTTP URL, you can avoid the hassle of changing the same configuration file on each server of the cluster.

Change the default setting

Here is the set of system properties that you can change

Name Description Default value
configurationSource.defaultFileName the default configuration file name on classpath config.properties
fixedDelayPollingScheduler.initialDelayMills Initial delay in milliseconds of reading from the configuration source 30000
fixedDelayPollingScheduler.delayMills Fixed delay in milliseconds between two reads of the configuration URLs 60000

Logging

Archaius uses SLF4J (http://www.slf4j.org/) for logging. SLF4J is a facade over logging that allows you to plug in any (or no) logging framework. See the SLF4J website for details.

Advanced Usage

Provide your own configuration source or polling scheduler

As explained in previous section, by default Archaius uses a set of URLs as configuration source and poll them in a fixed delay. However, you can also provide your own configuration source and/or polling scheduler. For example, you may define your own configuration source from a relational database, a distributed key-value store like Cassandra, or third party service as AWS SimpleDB.

To provide your own configuration source, follow these steps:

1. Implement com.netflix.config.PolledConfigurationSource 

public class DBConfigurationSource implements PolledConfigurationSource {
    // ...
    @Override
    public PollResult poll(boolean initial, Object checkPoint)
            throws Exception {
        // implement logic to retrieve properties from DB
    }  
}

2. (Optional) Provide your own scheduler by extending com.netflix.config.AbstractScheduler 

public class MyScheduler extends AbstractPollingScheduler {
    // ...
    @Override
    protected synchronized void schedule(Runnable runnable) {
        // schedule the runnable
    }

    @Override
    public void stop() {
        // stop the scheduler
    }
}

3. Create an instance of com.netflix.config.DynamicConfiguration 

  PolledConfigurationSource source = ...
  AbstractPollingScheduler scheduler = ...
  DynamicConfiguration configuration = new DynamicConfiguration(source, scheduler);

4. Register your configuration with com.netflix.config.DynamicPropertyFactory 

  DynamicPropertyFactory.initWithConfigurationSource(configuration);

5. Create dynamic properties from com.netflix.config.DynamicPropertyFactory 

  DynamicStringProperty myprop = DynamicPropertyFactory.getInstance().createStringProperty(...);

Use Archaius with your own Apache Commons Configuration implementation

If you already use or extend any type of AbstractConfiguration from Apache Commons Configuration, but would like to take advantage of Archaius to feed your application with dynamic properties, you can do this in two ways:

1. Use an implementation of com.netflix.config.AbstractPollingScheduler to poll the dynamic configuration source and put them into your own Configuration

  AbstractConfiguration myConfiguration = ...; // this is your original configuration
  // ...
  AbstractPollingScheduler scheduler = new FixedDelayPollingScheduler(); // or use your own scheduler
  PolledConfigurationSource source = new URLConfigurationSource(); // or use your own source
  scheduler.setIgnoreDeletesFromSource(true); // don't treat properties absent from the source as deletes
  scheduler.startPolling(source, myConfiguration);
  // ...
  DynamicPropertyFactory.initWithConfigurationSource(myConfiguration);

Now the original configuration becomes dynamic at runtime as properties from the polled configuration source will override their values in the original configuration. Note: In the above example, myConfiguration will be accessed from different threads and updates may not be visible immediately depending how the configuration is implemented. You can utilize com.netflix.config.ConcurrentMapConfiguration to ensure visibility of updates.

2. Use com.netflix.config.ConcurrentCompositeConfiguration 

  AbstractConfiguration myConfiguration = ...; // this is your original configuration

  // create the dynamic configuration
  AbstractPollingScheduler scheduler = new FixedDelayPollingScheduler(); // or use your own scheduler
  PolledConfigurationSource source = new URLConfigurationSource(); // or use your own source
  DynamicConfiguration dynamicConfig = new DynamicConfiguration(source, scheduler);
      
  ConcurrentCompositeConfiguration finalConfig = new ConcurrentCompositeConfiguration();
  // add them in this order to make dynamicConfig override myConfiguration
  finalConfig.add(dynamicConfig);
  finalConfig.add(myConfiguration);
  
  DynamicPropertyFactory.initWithConfigurationSource(finalConfig);

The later approach gives you the flexibility to add more types configurations down the road.

Clone this wiki locally