Key Concepts

AndHow Properties are static final constants and behave that way

AndHow Properties must be declaired as static final and the compiler enforces this (with the help of AndHow's annotation processor). This means that:

• A Property and its value are defined across the entire classloader just like a class definition

• AndHow Properties can be used to configure application or class behavior, but generally not a particular class instance

• Properties are immutable

• Once loaded during initiation, Property values are immutable

You can think of AndHow Properties as static final constants that pull their value from outside the application.

AndHow initializes and loads property values only once at startup

Initiation is AndHow's startup/bootstrap process where it discovers all Properties in your application, scans multiple configuration sources to load values for them, and validates them. This will only happen once in the lifecycle of the application and once completed, the list of Properties and their values will never change.

There is more detail about the initiation process on the Initiation page.

AndHow respects Java privacy modifiers

Internally, AndHow maps the property itself to the property's value. Thus, when a property is declared with a non-public modifier:

private final static StrProp PROP = StrProp.builder().build();

Only code able to hold a reference to PROP can retrieve it's value.

AndHow Fails Fast... and that is a good thing

A key design principal of AndHow is that a non-deterministic initiation or invalid or missing configuration values should be detected as early as possible and should be considered fatal. AndHow implements this in two ways:

• As discussed above, multiple attempts to initialize AndHow indicate a non-deterministic initiation and will result in a RuntimeException

• During initiation, all values for all properties are validated and a RuntimeException thrown if any property is invalid

The alternative to fail fast would be to fail late. If configuration problems are discovered, for example, only when they are used, an application might run for a few days, then a feature that hadn't been used up to that point is accessed and ~BOOM~ its invalid configuration is discovered by bringing the application down. It will probably be 4AM when you get the call.

Property Names are CaSe InSeNsItIvE

For compatibility with Windows environment variable names, property names are case insensitive. Proper case names are still used internally for reporting and when creating configuration sample files. One exception to this is JNDI, which is inherently case sensitive.

Whitespace Handling

Whitespace is generally removed from values, it is possible to assign whitespace text strings - See Whitespace Handling .

Null Handling

AndHow does not have an explicit null value that is distinct from a property value never being set. This follows from the fact that most property sources (property files, cmd line, etc) have no direct way to indicate a null or to distinguish it from an empty string. The currently handling is this:

• Attempting to set a property to an empty or all whitespace is ignored. The Trimmer trims the value to null, and null values are considered unset. (Empty strings & whitespace can be preserved for StrProp's - See above)

• Any property that is null/unset may have a value loaded for it by a subsequent loader.

• FlgProp is a special case: It emulates the behavior of a command line switch so that its presence alone, even without a value, marks its value as true.

Configuration Sources and Loaders

AndHow uses Loaders to load Property values from configuration sources such as System.Properties, environment variable, system properties, JNDI, properties files, etc.. Loaders work on a 'first win' basis: The first loader to find a non-null for a Property sets the value.

Thus, the loader order is significant and well established. The standard Loader order will work for most applications, but if needed, the load order can be changed, loaders removed and other loaders added.

Don't worry about Property names

While many configuration frameworks are based on a user defined String key for each property, you can safely 'forget' about naming AndHow properties. The strings used to refer to AndHow properties in configuration files, JNDI and other sources are the semantic paths of the Property declarations, e.g. a property named Boom in the class three.two.One has the name three.two.One.Boom. That means you don't have to name them and the Java complier ensures there are no naming collisions. You can still add aliases and sometimes you need to to Support for legacy applications.

Still, typing all those names in a configuration file is a drag, so AndHow will create samples files with all of your properties.