Users Guide

This document outlines how to use certain advanced features of Archaius.

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(...);

---

Using JConsole to view and update your properties at Runtime

If you set the following system property,

dynamicPropertyFactory.registerConfigWithJMX=true

the configuration registered with DynamicPropertyFactory will be automatically exposed to JMX, where you can update the properties via jconsole.

Alternatively, you can programmaically register your own configuration with an MBean:

  AbstractConfiguration config = ...
  ConfigJMXManager.registerConfigMbean(config);

The image above shows a screen capture of a view of the properties when the operation obtainProperties() is invoked.

Operations available are:

• obtainProperties() : Obtain all properties in the composite configuration
• getProperty(String key) : Obtain a particular property value given a key
• addProperty(String key, String value) : Add a new property into the CompositeConfiguration
• updateProperty(String key, String value) : Update the value of an existing property
• clearProperty(String key) : clear the property (delete)

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.