组态/图模一体化>> net.cactusthorn.config>> 返回
项目作者： Gmugra

项目描述 ：
Configuration library based on annotation processing
高级语言： Java
项目地址: git://github.com/Gmugra/net.cactusthorn.config.git
创建时间： 2021-04-04T06:09:34Z
项目社区：https://github.com/Gmugra/net.cactusthorn.config
开源协议：BSD 3-Clause "New" or "Revised" License
下载


net.cactusthorn.config

The Java library with the goal of minimizing the code required to handle application configuration.

build Coverage Status Codacy Badge Maven Central with version prefix filter GitHub Build by Maven

Table of Contents

Motivation

The inspiring idea for the project comes from OWNER. OWNER is a nice Java library for the same purpose, but it’s not factually maintained anymore, and it’s not really support “new” language features from Java 8+.

So, this project is providing library with similar with OWNER API, but

  • Based not on Reflection, but on compile-time Code Generation (Java Annotation Processing).
  • Required at least Java 11, as result it support “more fresh” language features.

Features

  • Core is plain Java 11 without any external dependencies

  • Uses no reflection or runtime bytecode generation; generates plain Java source code.

  • Small (< 100KB) & lightweight core runtime part

  • Ready to use with OSGi

  • Supports multiple configuration sources: files, classpath, URLs, environment variables, system properties, META-INF/MANIFEST.MF, Apache ZooKeeper

  • Supports files in Multiple formats:

  • Supports multiple loading strategies (configuration sources fallback/merging)

  • Expandable with custom source loaders

  • Powerful type conversions: collections, maps, enums, etc.

  • Parameterized type converters

  • Expandable with custom type converters

  • Special support for java.util.Optional, java.time.*, byte-size settings (e.g. 10Mb), Jasypt password-based encryption

  • Caching

  • Seamless integration with DI containers

  • Thread-safe

  • Reloading, Periodical auto reloading, Reload event listeners

Basics

Installing

Download: Maven Central Repository.

Download: GitHub Packages.

In order to use the library in a project, it’s need to add the dependency to the pom.xml:

  1. <dependency>
  2.     <groupId>net.cactusthorn.config</groupId>
  3.     <artifactId>config-core</artifactId>
  4.     <version>0.81</version>
  5. </dependency>

It’s also need to include the compiler used to convert annotated “source”-interfaces into the code:

  1. <plugin>
  2.     <groupId>org.apache.maven.plugins</groupId>
  3.     <artifactId>maven-compiler-plugin</artifactId>
  4.     <version>3.11.0</version>
  5.     <configuration>
  6.          <annotationProcessorPaths>
  7.               <path>
  8.                   <groupId>net.cactusthorn.config</groupId>
  9.                   <artifactId>config-compiler</artifactId>
  10.                   <version>0.81</version>
  11.               </path>
  12.          </annotationProcessorPaths>
  13.     </configuration>
  14. </plugin>

FYI: With this configuration, Maven will output the generated code into target/generated-sources/annotations.

Same with Gradle:

  1. api 'net.cactusthorn.config:config-core:0.81'
  2. annotationProcessor 'net.cactusthorn.config:config-compiler:0.81'

Basic usage

To access properties it’s need to define a convenient Java interface, e.g. :

  1. @Config
  2. @Prefix("app")
  3. public interface MyConfig {
  5.     @Default("unknown")
  6.     String val();
  8.     @Key("number")
  9.     int intVal();
  11.     Optional<URI> uri();
  13.     @Disable(PREFIX)
  14.     List<UUID> ids();
  16.     @Split("[,:;]")
  17.     @Default("DAYS;HOURS")
  18.     Set<TimeUnit> units();
  20.     @LocalDateParser({ "dd.MM.yyyy", "yyyy-MM-dd" })
  21.     LocalDate date();
  22. }
  • An interface must be annotated with @Config.
  • An interface must contain at least one method declaration (but methods declaration can be also in super interface(s)).
  • All methods must be without parameters

Based on the interface, the annotation processor will generate an implementation, that can be obtained using ConfigFactory:

  1. MyConfig myConfig =
  2.     ConfigFactory.builder()
  3.         .setLoadStrategy(LoadStrategy.MERGE)
  4.         .addSource("file:~/myconfig.xml")
  5.         .addSource("classpath:config/myconfig-owner.xml")
  6.         .addSource("jar:file:path/to/some.jar!/path/to/myconfig.properties")
  7.         .addSource("https://somewhere.com/myconfig.toml")
  8.         .addSource("file:./myconfig.json")
  9.         .addSource("file:./myconfig.yaml")
  10.         .build()
  11.         .create(MyConfig.class);

e.g. “myconfig.properties”:

  1. app.val=ABC
  2. app.number=10
  3. app.uri=http://java.sun.com/j2se/1.3/
  4. ids=f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454,123e4567-e89b-12d3-a456-556642440000
  5. app.units=DAYS:HOURS;MICROSECONDS
  6. app.date=12.11.2005

e.g. “myconfig.xml” (properties style xml):

  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
  3. <properties>
  4.     <entry key="app.val">ABC</entry>
  5.     <entry key="app.number">10</entry>
  6.     <entry key="app.uri">http://java.sun.com/j2se/1.3/</entry>
  7.     <entry key="ids">f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454,123e4567-e89b-12d3-a456-556642440000</entry>
  8.     <entry key="app.units">DAYS;HOURS;MICROSECONDS</entry>
  9.     <entry key="app.date">12.11.2005</entry>
  10. </properties>

e.g. “myconfig-owner.xml” (OWNER xml format):

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <app>
  3.     <val>ABC</val>
  4.     <number>10</number>
  5.     <uri>http://java.sun.com/j2se/1.3/</uri>
  6.     <units>DAYS;HOURS;MICROSECONDS</units>
  7.     <date>12.11.2005</date>
  8. </app>

e.g. “myconfig.toml” (TOML format):

  1. ids = ["f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454","123e4567-e89b-12d3-a456-556642440000"]
  3. [app]
  4. val = "ABC"
  5. number = 10
  6. uri = "http://java.sun.com/j2se/1.3/"
  7. units = ["DAYS", "HOURS", "MICROSECONDS"]
  8. date = 2005-11-12

e.g. “myconfig.json” (JSON format):

  1. {
  2.     "ids" : ["f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454", "123e4567-e89b-12d3-a456-556642440000"],
  3.     "app" : {
  4.         "val" : "ABC",
  5.         "number" : 10,
  6.         "uri" : "http://java.sun.com/j2se/1.3/",
  7.         "units" : ["DAYS", "HOURS", "MICROSECONDS"],
  8.         "date" : "2005-11-12"
  9.     }
  10. }

e.g. “myconfig.yaml” (YAML format):

  1. ids:
  2.   - f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454
  3.   - 123e4567-e89b-12d3-a456-556642440000
  4. app:
  5.   val: ABC
  6.   number: 10
  7.   uri: http://java.sun.com/j2se/1.3/
  8.   units:
  9.     - DAYS
  10.     - HOURS
  11.     - MICROSECONDS
  12.   date: '2005-11-12'

Annotations

  1. @Config

    • @Target(TYPE)
    • The “source” interface must be annotated with this annotation.

  2. @Factory

    • @Target(TYPE)
    • The “factory” interface must be annotated with this annotation.

  3. @Prefix

    • @Target(TYPE)
    • Set global prefix for all property names

  4. @Key

    • @Target(METHOD)
    • Set property name for the method. If this annotation is not present method-name will be used as property name

  5. @Default

    • @Target(METHOD)
    • Set default value (if property will not found in sources, the default value will be used).
    • Can’t be used for methods with Optional return type.

  6. @Disable

    • @Target({TYPE, METHOD})
    • Disable “global”-level features for this method.

  7. @Split

    • @Target({TYPE, METHOD})
    • Set splitter regular expression for splitting value for collections, or key+value “entries” for maps.
    • If this annotation is not present, default “splitter” is comma : ,

  8. @ConverterClass

    • @Target({METHOD, ANNOTATION_TYPE})
    • apply custom converter implementation

  9. @LocalDateParser, @LocalDateTimeParser, @LocalTimeParser, @ZonedDateTimeParser, @OffsetDateTimeParser, @OffsetTimeParser, @YearParser, @YearMonthParser, @MonthDayParser

    • @Target(METHOD)
    • apply a parameterized by formats converter to the relevant java.time.* type

  10. @PBEDecryptor

    • @Target(METHOD)
    • decrypt properties that were encrypted with Jasypt Password-Based Encryption. FYI: jasypt

Property not found : @Default or Optional

There are three ways for dealing with properties that are not found in sources:

  1. If method return type is not Optional and the method do not annotated with @Default, the ConfigFactory.create method will throw runtime exception “property … not found”

  2. If method return type is Optional -> method will return Optional.empty()

  3. If method return type is not Optional, but the method do annotated with @Default -> method will return converted to return type default value.

FYI:

  • The @Default annotation can’t be used with a method that returns Optional.
  • If method return type is List, Set, SortedSet, Map, SortedMap -> method will return empty collection or map.

@Config annotation parameters

There are two optional parameters sources and loadStrategy which can be used to override these settings from ConfigFactory.
e.g.

  1. @Config(sources = {"classpath:config/testconfig2.properties","nocache:system:properties"},
  2.         loadStrategy = LoadStrategy.FIRST)
  3. public interface ConfigOverride {
  5.     String string();
  6. }
  1. If sources parameter is present, all sources added in the ConfigFactory (using ConfigFactory.Builder.addSource methods) will be ignored.
  2. If loadStrategy parameter is present, it will be used instead of loadStrategy from ConfigFactory.
  3. Manually added properties (which added using ConfigFactory.Builder.setSource(Map<String, String> properties) method) are highest priority anyway. These properties will be merged in any case.

System properties and/or environment variables in @Key and/or @Prefix

The @Key and @Prefix annotations can refer to system properties or environment variables.

This feature makes it possible to store, for example, settings for different environments in a single configuration file. e.g. (TOML):

  1. host = "https://www.google.com/"
  2. port = 80
  4. [dev]
  5. host = "https://github.com/"
  6. port = 90
  8. [prod]
  9. host = "https://www.wikipedia.org/"
  10. port = 100

Syntax: {name} or {name:default-value}

e.g.

  1. @Config
  2. public interface MyServer {
  3.     @Key("{env}.host") URL host();
  4.     @Key("{env}.port") int port();
  5. }

or (with same result)

  1. @Config
  2. @Prefix("{env}")
  3. public interface MyServer {
  4.     URL host();
  5.     int port();
  6. }

usage e.g.:

  1. java -Denv=dev -jar myapp.jar

FYI:

  1. If a system property or environment variable does not exist, specified default-value will be used.
  2. If a system property or environment variable does not exist, and default-value not specified, an empty string will be used as the value.
  3. After expanding, start & end points . will be dropped.
  4. After expanding, multiple points (e.g ...) inside the key name will be substituted to single ..
system property value key config resulting key
dev {env}.host dev.host
{env}.host host
dev server.{env}.host server.dev.host
server.{env}.host server.host
dev host.{env} host.dev
host.{env} host
system property value key config resulting key
dev {env:test}.host dev.host
{env:test}.host test.host
dev server.{env:test}.host server.dev.host
server.{env:test}.host server.test.host
dev host.{env:test} host.dev
host.{env:test} host.test

The ConfigFactory

The ConfigFactory class is thread-safe, but not stateless.
It stores loaded properties in the internal cache (see Caching), and also control auto reloading.
Therefore, it certainly makes sense to create and use one single instance of ConfigFactory for the whole application.

Direct access to properties

It’s possible to get loaded properties without define config-interface.

  1. ConfigHolder holder =
  2.     ConfigFactory.builder()
  3.         .setLoadStrategy(LoadStrategy.FIRST)
  4.         .addSource("file:./myconfig.properties")
  5.         .addSource("classpath:config/myconfig.properties", "system:properties")
  6.         .build()
  7.         .configHolder();
  9. String val = holder.getString("app.val", "unknown");
  10. int intVal = holder.getInt("app.number");
  11. Optional<List<UUID>> ids = holder.getOptionalList(UUID::fromString, "ids", ",");
  12. Set<TimeUnit> units = holder.getSet(TimeUnit::valueOf, "app.units", "[:;]", "DAYS:HOURS");

@Factory annotation

There is one place where Java-reflection is used: ConfigFactory.create method.
@Factory annotation provides the ability to generate “Factory”-class(es) which helps to avoid reflection completely.

  1. @Config
  2. public interface MyConfig {
  3.     String val();
  4. }
  1. @Factory
  2. public interface MyFactory {
  3.     MyConfig createMyConfig();
  4. }
  1. MyConfig myConfig = Factory_MyFactory.builder().addSource("file:./myconfig.properties").build().createMyConfig();

As you can see, based on the MyFactory-interface annotated by @Factory, the class Factory_MyFactory will be generated, which has same API with ConfigFactory but instead of create-method it provides “create”-methods for the interface annotated by @Factory.
Restrictions:

  • an interface annotated by @Factory must contains at least one method
  • an interface annotated by @Factory must contains only methods without parameters
  • all methods of an interface annotated by @Factory must return only types annotated by @Config

Manually added properties

The ConfigFactory.Builder contains a method for adding properties manually: setSource(Map<String, String> properties).
Manually added properties are highest priority always: loaded by URIs properties merged with manually added properties, independent of loading strategy.
In other words: the manually added properties will always override (sure, when the property keys are same) properties loaded by URI(s).

There is two major use-cases for the feature: unit-tests & console applications.
For console applications, it is convenient to provide command line arguments to the ConfigFactory using this feature.

Caching

By default, ConfigFactory caches loaded properties using source-URI (after resolving system properties and/or environment variable in it) as a cache key.

To not cache properties related to the URI(s), use URI-prefix nocache: this will switch off caching for the URI.
e.g.

  • nocache:system:properties
  • nocache:file:~/my.properties

Global Prefix

The ConfigFactory.Builder provide the method to set global prefix setGlobalPrefix(String prefix), which will be used for all “config”-interfaces that will be created using the factory:

  1. app.val=ABC
  1. @Config
  2. public interface MyConfig {
  3.     String val();
  4. }
  1. MyConfig myConfig = ConfigFactory.builder().setGlobalPrefix("app").build().create(MyConfig.class);

This makes it possible to avoid @Prefix or/and @Key annotations, in case several “config”-interfaces are created based on the same source(s).
FYI:

  • Global-prefix is added before the prefix from the @Prefix annotation. They can be used together.
  • Global-prefix also support system properties and/or environment variables (like @Prefix and @Key)
  • Global-prefix can be switched off for the method or “config”-interface using @Disable(Disable.Feature.GLOBAL_PREFIX)

Type conversion

Supported method return types

The return type of the interface methods must either:

  1. Be a primitive type

  2. Have a public constructor that accepts a single String argument

  3. Have a public static method named valueOf or fromString that accepts a single String argument

    • e.g. Integer.valueOf
    • e.g. UUID.fromString
    • e.g. any enum
    • If both methods are present then valueOf used unless the type is an enum in which case fromString used.

  4. Be

    • java.net.URL
    • java.net.URI
    • java.nio.file.Path
    • java.util.Currency
    • java.util.Locale
    • java.util.regex.Pattern
    • java.time.Instant
    • java.time.Duration
    • java.time.Period
    • java.time.LocalDate
    • java.time.LocalDateTime
    • java.time.LocalTime
    • java.time.ZonedDateTime
    • java.time.OffsetDateTime
    • java.time.OffsetTime
    • java.time.Year
    • java.time.YearMonth
    • java.time.MonthDay
    • java.time.ZoneId
    • java.time.ZoneOffset
    • net.cactusthorn.config.core.converter.bytesize.ByteSize

  5. Be List<T>, Set<T> or SortedSet<T>, where T satisfies 2, 3 or 4 above. The resulting collection is read-only.

  6. Be Map<K,V> or SortedMap<K,V>, where

    • K satisfies 2, 3 or 4 above.
    • V satisfies 2, 3 or 4 above.
    • The resulting map is read-only.

  7. Be Optional<T>, where T satisfies 2, 3 or 4 above

Maps

Maps support is limited to two restrictions:

  1. custom converters are not supported for the key
  2. as key-value separator can be used only | (pipe character)

e.g. “myconfig.properties”:

  1. map=A|10,BBB|20
  2. map2=10000|10;20000|20
  1. @Config(sources="classpath:/myconfig.properties")
  2. public interface ConfigMap {
  4.     Map<String, Integer> map();
  6.     @Split(";") Optional<Map<Integer, Byte>> map2();
  8.     @Default("123e4567-e89b-12d3-a456-556642440000|https://github.com") Map<UUID, URL> map3();
  9. }

FYI:

  1. In case of Maps, @Split annotation set splitter for key+value “entries” (default “splitter” is comma : ,).
  2. In case of Maps, the annotations associated with converters( e.g. @ConverterClass, @ZonedDateTimeParser etc.) only affect the Map values.

java.util.Locale format

The string must be well-formed BCP 47 language tag.
https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#forLanguageTag-java.lang.String-
e.g. de-DE

java.time.Instant format

The string must represent a valid instant in UTC and is parsed using DateTimeFormatter.ISO_INSTANT
e.g. 2011-12-03T10:15:30Z

java.time.Duration formats

  1. Standard ISO 8601 format, as described in the JavaDoc for java.time.Duration. e.g. P2DT3H4M

  2. “unit strings” format:

    1. Bare numbers are taken to be in milliseconds: 10

    2. Strings are parsed as a number plus an optional unit string: 10ms, 10 days

    3. The supported unit strings for duration are case sensitive and must be lowercase. Exactly these strings are supported:

      • ns, nano, nanos, nanosecond, nanoseconds
      • us, µs, micro, micros, microsecond, microseconds
      • ms, milli, millis, millisecond, milliseconds
      • s, second, seconds
      • m, minute, minutes
      • h, hour, hours
      • d, day, days

java.time.Period formats

  1. Standard ISO 8601 format, as described in the JavaDoc for java.time.Period. e.g. P1Y2M3W4D

  2. “unit strings” format:

    1. Bare numbers are taken to be in days: 10

    2. Strings are parsed as a number plus an optional unit string: 10y, 10 days

    3. The supported unit strings for duration are case sensitive and must be lowercase. Exactly these strings are supported:

      • d, day, days
      • w, week, weeks
      • m, mo, month, months
      • y, year, years

net.cactusthorn.config.core.converter.bytesize.ByteSize format

It based on OWNER classes to represent data sizes.

usage:

  1. @Config
  2. public interface MyByteSize {
  4.     @Default("10 megabytes")
  5.     net.cactusthorn.config.core.converter.bytesize.ByteSize size();
  6. }

The supported unit strings for ByteSize are case sensitive and must be lowercase. Exactly these strings are supported:

  • byte, bytes, b
  • kilobyte, kilobytes, k, ki, kib
  • kibibyte, kibibytes, kb
  • megabyte, megabytes, m, mi, mib
  • mebibyte, mebibytes, mb
  • gigabyte, gigabytes, g, gi, gib
  • gibibyte, gibibytes, gb
  • terabyte, terabytes, t, ti, tib
  • tebibyte, tebibytes, tb
  • petabyte, petabytes, p, pi, pib
  • pebibyte, pebibytes, pb
  • exabyte, exabytes, e, ei, eib
  • exbibyte, exbibytes, eb
  • zettabyte, zettabytes, z, zi, zib
  • zebibyte, zebibytes, zb
  • yottabyte, yottabytes, y, yi, yib
  • yobibyte, yobibytes, yb

Custom converters

If it’s need to deal with class which is not supported “by default” (see Supported method return types), a custom converter can be implemented and used.

  1. public class MyClassConverter implements Converter<MyClass> {
  3.     @Override public MyClass convert(String value, String[] parameters) {
  4.         ...
  5.     }
  6. }

The @ConverterClass annotation allows to specify the Converter-implementation for the config-interface method:

  1. @Config public interface MyConfigWithConverter {
  3.     @ConverterClass(MyClassConverter.class) @Default("some super default value") MyClass theValue();
  5.     @ConverterClass(MyClassConverter.class) Optional<MyClass> mayBeValue();
  7.     @ConverterClass(MyClassConverter.class) Optional<List<MyClass>> values();
  9.     @ConverterClass(MyClassConverter.class) Optional<Map<Path, MyClass>> map();
  10. }

FYI:

  1. Converter-implementation must be stateless and must have a default(no-argument) public constructor.
  2. Converter-implementation can be used instead “standard” converting, so it’s possible to implement specific converting for supported by default types.
  3. Converter-implementation can be used for interface or abstract class
  4. In case of maps, Converter-implementation are using only for values(not for keys)

Parameterized custom converters

Sometimes it’s convenient to set several constant parameters for the custom converter.
For example, to provide format(s) with a converter for date-time types.
This can be achieved with converter-annotation for the custom-converter:

  1. @Retention(SOURCE)
  2. @Target(METHOD)
  3. @ConverterClass(MyClassConverter.class) //converter implementation
  4. public @interface MySuperParser {
  6.     String[] value() default "";
  7. }

FYI:

  • the annotation must contains String[] value() default "" parameter, otherwise parameters will be ignored by compiler
  • the annotation can be made for any converter (even for converter which is, actually, not need parameters)

usage:

  1. @Config
  2. public interface MyConfig {
  4.     @MySuperParser({"param1", "param1"})
  5.     MyClass myValue();
  6. }

Several of these annotations shipped with the library:

Loaders

Standard loaders

  1. System properties: system:properties

  2. Environment variables: system:env

  3. properties file from class-path : classpath:relative-path-to-name.properties[#charset]

    • Default charset (if URI fragment not present) is UTF-8
    • e.g. classpath:config/my.properties#ISO-5589-1

  4. properties file from any URI convertable to URL: whatever-what-supported.properties[#charset]

    • Default charset (if URI fragment not present) is UTF-8
    • e.g. the file from the working directory: file:./my.properties
    • e.g. Windows file: file:///C:/my.properties
    • e.g. web: https://raw.githubusercontent.com/Gmugra/net.cactusthorn.config/main/core/src/test/resources/test.properties
    • e.g. jar in file-system: jar:file:path/to/some.jar!/path/to/your.properties

  5. XML file from class-path : classpath:relative-path-to-name.xml[#charset]

    • XML format: properties.dtd or OWNER
    • Default charset (if URI fragment not present) is UTF-8
    • e.g. classpath:config/my.xml#ISO-5589-1

  6. XML file from any URI convertable to URL: whatever-what-supported.xml[#charset]

    • XML format: properties.dtd or OWNER
    • Default charset (if URI fragment not present) is UTF-8
    • e.g. file:./my.xml

  7. META-INF/MANIFEST.MF: classpath:jar:manifest?attribute[=value]

    • The loader scans all JARs in classpath for META-INF/MANIFEST.MF files. First META-INF/MANIFEST.MF, which contain attribute (with optional value) from the URI will be used as source.
    • e.g. MANIFEST.MF must contain attribute Bundle-Name with value JUnit Jupiter API: classpath:jar:manifest?Bundle-Name=JUnit%20Jupiter%20API
    • e.g. MANIFEST.MF must contain attribute exotic-unique-attribute with any value: classpath:jar:manifest?exotic-unique-attribute

Custom loaders

It’s possible to implement custom loaders using Loader interface.
This makes it possible to load properties from specific sources (e.g. Database) or to support alternative configuration-file formats.
e.g.

  1. public final class SinglePropertyLoader implements Loader {
  3.     @Override public boolean accept(URI uri) {
  5.         return uri.toString().equals("single:property");
  6.     }
  8.     @Override public Map<String, String> load(URI uri, ClassLoader classLoader) {
  10.         Map<String, String> result = new HashMap<>();
  11.         result.put("key", "value");
  12.         return result;
  13.     }
  14. }
  1. ConfigFactory factory =
  2.     ConfigFactory.builder()
  3.     .addLoader(SinglePropertyLoader.class)
  4.     .addSource("single:property")
  5.     .build();

FYI:

  • Custom loaders always have the highest priority if added using ConfigFactory.Builder.addLoader method: last added -> first used.
  • Custom loader implementation must be stateless and must have a default(no-argument) public constructor.

SPI

Service-provider loading facility (introduced in JDK 1.6) can be used to automatically add custom loader implementation to the ConfigFactory. Simple add file META-INF\services\net.cactusthorn.config.core.loader.Loader with full-class-name of custom-loader implementation(s) in the class path.
e.g.

System properties and/or environment variables in sources URIs

Syntax: {name} or {name:default-value}
e.g.

  • file:/{config-path}/my.properties
  • classpath:{config-path:home}/my.properties#{charset}

FYI:

  • If a system property or environment variable does not exist and default-value is not specified, an empty string will be used as the value.

Special use-case user home directory: The URIs with file:~/ (e.g. file:~/my.xml or jar:file:~/some.jar!/your.properties) always correctly resolved to user home directory independent from OS.

  • e.g. in Windows, URI file:~/my.xml will be replaced to file:///C:/Users/UserName/my.xml.

Loading strategies

ConfigFactory saves the sequence in which the sources URIs were added.

  1. MyConfig myConfig =
  2.     ConfigFactory.builder()
  3.         .setLoadStrategy(LoadStrategy.FIRST)
  4.         .addSource("file:/myconfig.properties", "classpath:config/myconfig.properties")
  5.         .build()
  6.         .create(MyConfig.class);

Loading strategies:

  • FIRST - only the first (in the sequence of adding) existing and not empty source will be used.
  • MERGE - merging all properties from first added to last added.
  • FIRST_KEYCASEINSENSITIVE - same with FIRST, but property keys are case insensitive
  • MERGE_KEYCASEINSENSITIVE - same with MERGE, but property keys are case insensitive
  • FIRST_KEYRELAXED - same with FIRST, but property keys are “relaxed”.
  • MERGE_KEYRELAXED - same with MERGE, but property keys are “relaxed”.
  • Default strategy is MERGE

“Relaxed”:

  • keys are case insensitive
  • .(dot), -(minus) and _(underscore) characters are ignored
  • For example: person.first-name, person.firstName and PERSON_FIRSTNAME can all be used interchangeably.

Warning: Manually added properties (which added using ConfigFactory.Builder.setSource(Map<String, String> properties) method) are highest priority always. So, loaded by URIs properties merged with manually added properties, independent of loading strategy.

Periodical auto reloading

ConfigFactory can automatically reload configurations which extends net.cactusthorn.config.core.Reloadable interface.
To activate auto-reloading need to set “periodInSeconds” using autoReload method:

  1. ConfigFactory factory =
  2.     ConfigFactory.builder()
  3.         .addSource("file:/myconfig.properties")
  4.         .autoReload(5) //reload every 5 seconds
  5.         .build();

Warning: If you do not call autoReload method, auto reloading will not work.

But, the source will be reloaded only if it changed.
Loader-implementation should implement contentHashCode method which return hash-code. (The method return value should be changed, when URI related content is changed).
If Loader-implementation do not support auto-reloading (which is default behavior) the method is returns always same value (e.g. 0).
As result, for the moment, auto reloading only supported for:

  • system:properties
  • URIs with file: scheme (only files related URIs). FYI: file last-modified-time is used as hash-code.

Warning: Be careful, non-cached(nocache:) sources will always be reloaded, whether they are modified or not.

It is possible to disable auto reloading for the “config”-interface, even if it is activated:

  1. @Config
  2. @Disable(Disable.Feature.AUTO_RELOAD)
  3. public interface MyConfig extends Reloadable {
  4.     String value();
  5. }

Filesystems quirks
The date resolution vary from filesystem to filesystem.
For instance, for Ext3, ReiserFS and HSF+ the date resolution is of 1 second.
For FAT32 the date resolution for the last modified time is 2 seconds.
For Ext4 the date resolution is in nanoseconds.

Reload event listeners

It would be nice to know which properties has changed as result of reloading, so that you can e.g. re-configure only the affected services.
It’s possible to achieve using “Reload event listeners” feature.
Example how to do it: ListenerTest

Interfaces

Interfaces inheritance

Interfaces inheritance is supported.
e.g.

  1. interface MyRoot {
  3.     @Key(rootVal) String value();
  4. }
  1. @Config
  2. interface MyConfig extends MyRoot {
  4.     int intValue();
  5. }
  • There is no limit to the number and “depth” of super-interfaces.
  • Interface level annotations (e.g. @Prefix) on super-interfaces will be ignored.

java.io.Serializable

“config”-interface can extends (directly or over super-interface) java.io.Serializable.
In this case generated class will also get private static final long serialVersionUID attribute.

  1. @Config
  2. public interface MyConfig extends java.io.Serializable {
  4.     long serialVersionUID = 100L;
  6.     String val();
  7. }

The interface (as in the example before) can, optionally, contains long serialVersionUID constant.
If the constant is present, the value will be used for the private static final long serialVersionUID attribute in the generated class.
Otherwise generated class will be generated with private static final long serialVersionUID = 0L.

net.cactusthorn.config.core.Accessible

“config”-interface can extends (directly or over super-interface) net.cactusthorn.config.core.Accessible.
In this case generated class will also get methods for this interface:

  1.     Set<String> keys();
  3.     Object get(String key);
  5.     Map<String, Object> asMap();

net.cactusthorn.config.core.Reloadable

“config”-interface can extends (directly or over super-interface) net.cactusthorn.config.core.Reloadable.
In this case generated class will also get methods for this interface:

  1.     void reload();
  3.     boolean autoReloadable();
  5.     void addReloadListener(ReloadListener listener);

FYI: The method always reload not cached sources, even if they not changed (see Caching)

Miscellaneous

Extras

“Extras” are optional extensions (converters and loaders) that need external dependencies and therefore can’t be integrated into the core library.

Logging

The runtime part of the library is using System.Logger.
This way, you can use any logging library you prefer:

  • Apache Log4j 2 -> org.apache.logging.log4j:log4j-jpl
  • SLF4J -> org.slf4j:slf4j-jdk-platform-logging

Profiles

There is no specific support for profiles, but it is easy to achieve similar behavior using System properties and/or environment variables in sources URIs,
e.g.:

  1. ConfigFactory.builder()
  2.     .addSource("file:~/myconfig-{myapp.profile}.properties")
  3.     .addSource("file:./myconfig-{myapp.profile}.properties")
  4.     .addSource("classpath:myconfig.properties")
  5.     .build();

and get profile from, for example, system property:

  1. java -Dmyapp.profile=DEV -jar myapp.jar

Integration with DI containers

Example with Dagger 2:

Eclipse IDE

It does not have annotation-processing enabled by default. To get it, you must install m2e-apt from the eclipse marketplace: https://immutables.github.io/apt.html

LICENSE

net.cactusthorn.config is released under the BSD 3-Clause license. See LICENSE file included for the details.