Skip to content

Improve README #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanaustin merged 6 commits into from
Jul 12, 2019
Merged

Improve README #25

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fffab23
Better detail in README.
jonathanaustin Jul 9, 2019
30eb7f2
Update README
jonathanaustin Jul 12, 2019
1ee71b9
Update README
jonathanaustin Jul 12, 2019
b288e28
Update README
jonathanaustin Jul 12, 2019
d8a7b50
Update README.md
jonathanaustin Jul 12, 2019
75a426a
Update README.md
jonathanaustin Jul 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 182 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
# Config
Project configuration mechanism.

## Status
# Status
[![Build Status](https://travis-ci.com/BorderTech/java-config.svg?branch=master)](https://travis-ci.com/BorderTech/java-config)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=bordertech-java-config&metric=alert_status)](https://sonarcloud.io/dashboard?id=bordertech-java-config)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=bordertech-java-config&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=bordertech-java-config)
Expand All @@ -10,28 +7,192 @@ Project configuration mechanism.
[![Javadocs](https://www.javadoc.io/badge/com.github.bordertech.config/config.svg)](https://www.javadoc.io/doc/com.github.bordertech.config/config)
[![Maven Central](https://img.shields.io/maven-central/v/com.github.bordertech.config/config.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.bordertech.config%22%20AND%20a:%22config%22)

# Why Use Config?
The `Config` class provides a standard mechanism java applications can use to access configuration data via the [Apache Commons Configuration](https://commons.apache.org/proper/commons-configuration/index.html) interface.
# Contents

- [What is Config?](#what-is-config)
- [Why use Config?](#why-use-config)
- [Getting started](#getting-started)
- [Features](#features)
- [Initialization](#initialization)
- [Contributing](#contributing)

# What is Config?
Project configuration mechanism.

# Why use Config?
The [Config](https://github.com/BorderTech/java-config/blob/master/src/main/java/com/github/bordertech/config/Config.java) class provides a standard mechanism java applications can use to access configuration data via the [Apache Commons Configuration](https://commons.apache.org/proper/commons-configuration/index.html) interface.

The [features](#features) of the [Default Configuration](https://github.com/BorderTech/java-config/blob/master/src/main/java/com/github/bordertech/config/DefaultConfiguration.java) combine and enhance the functionality of the classic [PropertiesConfiguration](https://commons.apache.org/proper/commons-configuration/apidocs/org/apache/commons/configuration2/PropertiesConfiguration.html) and [SystemConfiguration](https://commons.apache.org/proper/commons-configuration/apidocs/org/apache/commons/configuration2/SystemConfiguration.html) with predefined property file resources.

Projects can easily override this default implementation via the [initialization](#initialization) settings.

# Getting started

Add dependency:

``` xml
<project>
....
<dependency>
<groupId>com.github.bordertech.config</groupId>
<artifactId>config</artifactId>
<version>1.0.4</version>
</dependency>
....
</project>
```

`Config.getInstance()` is the central access point to the configuration mechanism. Configuration properties can be read from the current configuration as follows:

``` java
....
// Retrieve a property `my.example` with a default value
String value = Config.getInstance().getString("my.example", "a-default-value");
....
```

To override the `my.example` property, create a `bordertech-app.properties` file in the resources directory and add the following:

``` java properties
my.example=a-override-value
```

# Features

## Predefined property resources

The default implementation looks for the following resources:

- `bordertech-defaults.properties` - framework defaults
- `bordertech-app.properties` - application properties
- `bordertech-local.properties` - local developer properties

Projects will usually use `bordertech-app.properties` resource files.

The priority of the properties is in reverse order to the list of resources (i.e. `local` overrides `app` which overrides `defaults`).

The resources loaded into the Configuration can be overridden via [initialization](#initialization) settings.

## Include resources

Other property files can be included from the predefined property files:

``` java properties
include=another.properties
```

## Environment Suffix

It is possible to define properties to only take effect in a certain environment.

When the environment property is set, it is used as the suffix for each property lookup:

``` java properties
## MOCK Environment
bordertech.config.environment=MOCK

my.example.property.MOCK=mocking
my.example.property.PROD=proding
my.example.property=defaulting
```

If no property exists with the current environment suffix then the default property (ie no suffix) value is used.

# How Config Works
The `Config` class is the central access point to the configuration mechanism, and is used to read or modify the
current configuration.
## Touchfile

The library is configured using the [Apache Commons Configuration](https://commons.apache.org/proper/commons-configuration/index.html) interface. This allows developers to programmatically integrate the configuration with whatever mechanism is used to configure their applications.
The reload of the configuration can be triggered via a `touchfile`. The `touchfile` can be set via the property:

The default resources `Config` looks for are:-
* `bordertech-defaults.properties` - framework defaults
* `bordertech-app.properties` - application properties
* `bordertech-local.properties` - local developer properties
``` java properties
bordertech.config.touchfile=my-touchfile.properties
```

The default configuration can be overridden by setting properties in a file `bordertech-config.properties`.
To avoid excessive IO an interval (in milli seconds) between checks can be set and defaults to 10000:

The following properties can be set:-
* `bordertech.config.default.impl` - Default implementation class name
* `bordertech.config.spi.enabled` - enable SPI lookup (default `true`)
* `bordertech.config.spi.append.default` - append the default configuration (default `true`)
* `bordertech.config.resource.order` - order of resources to load into the configuration
``` java properties
bordertech.config.touchfile.interval=3000
```

## Merge System Properties into Configuration

Sometimes you may need to include System Properties in the Configuration:

|Property key|Description|Default value|
|-------------|-----------|-------------|
|bordertech.config.parameters.useSystemProperties|This flag allows system properties to be merged into the Configuration at the end of the loading process.|false|
|bordertech.config.parameters.useSystemOverWriteOnly|This flag controls if a system property will only overwrite an existing property|true|
|bordertech.config.parameters.useSystemPrefixes|Define a list of system attribute prefixes that are allowed to be merged. Default is allow all.|n/a|

## Merge Configuration into System Properties

Sometimes you may need to merge Configuration properties into the System Properties:

|Property key|Description|Default value|
|-------------|-----------|-------------|
|bordertech.config.parameters.system.\*|Parameters with this prefix will be dumped into the System parameters. Not for general use|n/a|


## Logging

The default implementation uses [SimpleLog](https://commons.apache.org/proper/commons-logging/apidocs/org/apache/commons/logging/impl/SimpleLog.html). This Simple implementation of Log sends all enabled log messages, for all defined loggers, to System.err.

Other logging options:

|Property key|Description|Default value|
|-------------|-----------|-------------|
|bordertech.config.parameters.dump.console|This flag allows properties to be dumped to the console after being loaded.|false|
|bordertech.config.parameters.dump.file|The file name to dump the properties to after being loaded.|n/a|

## Property listeners

Property listeners can be set on the `Config` to be notified whenever the `Config` is set or reloaded.

``` java
Config.addPropertyChangeListener(new MyListener());
```

## Testing

The following methods in the `Config` class are useful for unit testing:

- `reset()` - will restore the configuration.
- `copyConfiguration(Configuration)` - will perform a deep-copy of the given configuration. This is useful when you need to create a backup copy of the current configuration before modifying it for a particular test.

# Initialization

The initial configuration of `Config` can be overridden by setting properties in a file `bordertech-config.properties`.

The following options can be set:-

|Property key|Description|Default value|
|-------------|-----------|-------------|
|bordertech.config.default.impl|Default Configuration implementation class name|com.github.bordertech.config.DefaultConfiguration|
|bordertech.config.spi.enabled|The flag to enable SPI lookup|true|
|bordertech.config.spi.append.default|The flag to append the default configuration|true|
|bordertech.config.resource.order|The list of property resources to load into the configuration. Priority of properties is in reverse order of the list.|bordertech-defaults.properties, bordertech-app.properties, bordertech-local.properties|

## Default Implementation

Example of overriding the default implementation:

``` java properties
bordertech.config.default.impl=my.example.SpecialConfiguration
```

## Custom Resources to Load

Example of loading the default resources and a project specific resource:

``` java properties
bordertech.config.resource.order+=my-project.properties
```

## SPI
`ConfigurationLoader` is the SPI interface for classes that can load a custom configuration.

[ConfigurationLoader](https://github.com/BorderTech/java-config/blob/master/src/main/java/com/github/bordertech/config/ConfigurationLoader.java) is the [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) interface for classes that can load a custom configuration.

By default, the SPI lookup is enabled and if found, will be appended to the default implementation.


# Contributing

Refer to these guidelines for [Workflow](https://github.com/BorderTech/java-common/wiki/Workflow) and [Releasing](https://github.com/BorderTech/java-common/wiki/Releasing).