Features

Archaius is a Java library that provides APIs to access and utilize properties that can change dynamically at runtime. It includes the following features:

Dynamic properties

Archaius provides classes that represent dynamic properties where the values are of specific types and can change at runtime.

Instead of writing code like this to deal with something hard to change at runtime:

  String prop = System.getProperty("myProperty");
  int x = DEFAULT_VALUE;
  try {
      x = Integer.parseInt(prop);
  } catch (NumberFormatException e) {
      // handle format issues
  }
  myMethod(x);
  // ...

You can write much cleaner code to take advantage of a dynamic and type specific property:

  DynamicIntProperty prop = 
      DynamicPropertyFactory.getInstance().createIntProperty("myProperty", DEFAULT_VALUE);
  // prop.get() may change value at runtime
  myMethod(prop.get());

In addition, you can add callback listener to be notified when the property is changed:

  prop.addCallback(new Runnable() {
      public void run() {
          // ...
      }
  });

A polling framework for dynamic configuration sources

Out of the box, in a fixed interval, DynamicPropertyFactory will load configuration sources from a predefined local file on classpath as well as a set of URLs defined in a system property.

Archaius also provides an implementation of JDBC based configuration source.

You can define your own configuration source and poll scheduler by extending appropriate interface/class, and programmatically set it as the backing source of dynamic properties.

  PolledConfigurationSource source = createMyOwnSource();
  AbstractPollingScheduler scheduler = createMyOwnScheduler();
  DynamicPropertyFactory.initWithConfigurationSource(new DynamicConfiguration(source, scheduler));

High throughput and thread-safe configurations

Archaius provides a set of configurations that extend Apache’s Common Configuration where you can read/write properties and fire events concurrently. It also provides functionality to organize sub-configurations into an hierarchy from which the value of a property can be determined.

  // configuration from local properties file
  String fileName = "...";
  ConcurrentMapConfiguration configFromPropertiesFile =
      new ConcurrentMapConfiguration(new PropertiesConfiguration(fileName));
  // configuration from system properties
  ConcurrentMapConfiguration configFromSystemProperties = 
      new ConcurrentMapConfiguration(new SystemConfiguration());
  // configuration from a dynamic source
  PolledConfigurationSource source = createMyOwnSource();
  AbstractPollingScheduler scheduler = createMyOwnScheduler();
  DynamicConfiguration dynamicConfiguration =
      new DynamicConfiguration(source, scheduler);
  
  // create a hierarchy of configuration that makes
  // 1) dynamic configuration source override system properties and,
  // 2) system properties override properties file
  ConcurrentCompositeConfiguration finalConfig = new ConcurrentCompositeConfiguration();
  finalConfig.add(dynamicConfiguration, "dynamicConfig");
  finalConfig.add(configFromSystemProperties, "systemConfig");
  finalConfig.add(configFromPropertiesFile, "fileConfig");

  // register with DynamicPropertyFactory so that finalConfig
  // becomes the source of dynamic properties
  DynamicPropertyFactory.initWithConfigurationSource(finalConfig);