OWNER

What This Fork Does

The original purpose of this fork is implementing a non-breaking feature to the original, indeed great, project by supporting Optional as the returned config value.

For example, we turn what's on left to what's on the right in the table below

Original	Fork
import org.aeonbits.owner.Config; public interface ServerConfig extends Config { int port(); String hostname(); @DefaultValue("8") int maxNumThreads(); List<String> listProperty(); }	import org.aeonbits.owner.Config; public interface ServerConfig extends Config { Optional<Integer> port(); Optional<String> hostname(); @DefaultValue("8") Optional<Integer> maxNumThreads(); List<String> listProperty(); }

The feature is based on the 3 rationals below:

1. Method should "return empty arrays or collections, instead of nulls" (Effective Java, Joshua Bloch, 2nd Edition, Item 43)
2. For better error handling, our methods "don't return null" (Clean Code, Robert C. Martin, 2009, Ch. 7, Don't Return Null)
3. Oracle designed Optional, which was exactly intended to replace null with a new standard.

What this feature brings to our team, and others in general, is that it allows us to promote null-check at compile-time. Our team believes compile-time check is good by reducing runtime-errors.

"Why not using the original's @ConverterClass or a wrapper?"

Because we tried and concluded they are suboptimal in our case:

1. This would require every single of our applications to load an extra converter class
2. ConverterClass, i.e. Optional<?>, due to type erasure, loses type information, i.e. <?>, which original project does need in order to do proper conversion

At this moment, the fork allows the following config value types to be wrapped inside Optional:

• Boolean
• Integer
• String
• All Collection classes that the original project supports

We will keep working to catch up with all types supported by the original project.

OWNER, an API to ease Java property files usage.

INTRODUCTION

The goal of OWNER API is to minimize the code required to handle application configuration through Java properties files.

Full documentation available on project website.

BASIC USAGE

The approach used by OWNER APIs, is to define a Java interface associated to a properties file.

Suppose your properties file is defined as ServerConfig.properties:

port=80
hostname=foobar.com
maxThreads=100

To access this property you need to define a convenient Java interface in ServerConfig.java:

public interface ServerConfig extends Config {
    int port();
    String hostname();
    int maxThreads();

    @DefaultValue("77")
    Optional<Integer> someInteger();
}

We'll call this interface the Properties Mapping Interface or just Mapping Interface since its goal is to map Properties into a an easy to use piece of code.

Then, you can use it from inside your code:

public class MyApp {
    public static void main(String[] args) {
        ServerConfig cfg = ConfigFactory.create(ServerConfig.class);
        System.out.println("Server " + cfg.hostname() + ":" + cfg.port() +
                           " will run " + cfg.maxThreads());
    }
}

But this is just the tip of the iceberg.

Continue reading here: Basic usage.

DOWNLOAD

Public Releases can be downloaded from GitHub Packages page

DOCUMENTATION

Make sure to have a look at the documentation on project website to learn how flexible and powerful OWNER is, and why you may need it!

Chinese documentation is provided by Yunfeng Cheng via a GitHub independent project at this address.

LICENSE

OWNER is released under the BSD license. See LICENSE file included for the details.