2.0.0-M1: Massive architectural changes

Version 2.0 is a complete rewrite of DazzleConf and the library internals, making the whole library extensible and achieving proper decoupling between components. With these API improvements, version 2.0 seeks to overturn the brittle design of 1.0.

This version is a milestone release of version 2.0. APIs may still change and should not be considered. Feedback is very welcome at this time, and you have the opportunity to contribute library aspects that will benefit the whole community.

A broad overview of changes in version 2.0 onward:

• All types follow the same model, and API users can swap out handling of "built-in" types.
• Changed how default methods work: in version 2.0, default methods provide the default value of the configuration option (#20).
• Optional allow the user to omit the key entirely (#28).
• The library now collects multiple user errors and reports them all at once (#42).
• User-facing error messages can also be translated.
• API design now prevents an entire collection of sub-sections from being reset just because one sub-section was missing a key (#31).
• Added type liaison API, a comprehensive replacement for "ValueSerialiser."
• Added read-update-modify operation, the new backbone of the library.
• Added migrations API.
• Added "reload shell" API, letting you reload the "real" configuration behind it (#21).
• Instantiated configurations now implement equals/hashCode based on their content., i.e. if all methods yield the same values. Previously, 1.x used identity equality.
• Added "if missing" option for default values (#36).
• Full round-trip for YAML backend comments. YAML now uses version 1.2 of the spec.
• TOML support (#12).
• Configuration backend is fully decoupled from the core library, so you can use things like loadDefaults() with just the core library.
• Map method names to configuration keys automatically, using the backend style (e.g. myMethod() -> my-method for YAML) and deprecate @ConfKey (#38).
• Removed items:
  • No more BadValueException and associated mess from it. 2.0 uses LoadResult which is a result-container object.
  • No more configuration sorting. Instead, we aim to preserve order at every step of the way..
  • No more ConfValidator or ValueValidator. You should use a custom type if you want to add extra preconditions.

For more detailed documentation and changes, you should view the /docs/ folder of this repository. In particular, docs/Update-to-2.0.md describes how to transition your library usage to this version.

As always, contributions are highly welcome, and so is feedback. This is a very big release with many changes, and much is still up in the air.

1.4.0: Transition release

This special release track forks the main artifact, and it provides 1.x and 2.x APIs side-by-side. It splits packages into the following:

• space.arim.dazzleconf - 1.x APIs
• space.arim.dazzleconf2 - 2.x APIs, with the package name changed.

Please see docs/Update-to-2.0.md for why you might want to use this artifact.

1.3.0-RC1: Capitalizing on maturity while preparing for version 2.0

This series, 1.3.0, will be the last DazzleConf release track before API 2.0. At this point, DazzleConf 1.x is largely stable and has seen plenty of usage. However, it suffers architectually from a number of flaws, which is why version 2.0 is in development. This release, 1.3.0-RC1, stabilizes the changes in 1.3.0-M1 and 1.3.0-M2 and adds some changes of its own.

The features deprecated by this release -- dotted key paths, value validators, and @ConfSerialisers -- will be removed without replacement in version 2.0.

Bug fixes:

• Tell Gson to give us accurate long values. Affects using very big longs with dazzleconf-ext-gson (#44)

Deprecations:

• Dotted key paths in @ConfKey. This is a strange way of specifying sub-paths, that I hope no one uses - #24
• ValueValidator and @ConfValidator
• @ConfSerialisers

---

Migration

Dotted key paths in @ConfKey are now disabled by default. Using them will throw an exception. To re-enable them, you have to set a flag in ConfigurationOptions. This can be done like so:

ConfigurationOptions configOptions = new ConfigurationOptions.Builder().setDottedPathInConfKey(true).build();

Migration checklist from 1.2.x:

• Dotted key paths are now disabled by default. To re-enable them, see above.
• Since 1.3.0-M1: Null collection elements are now (correctly) prohibited. If you were accidentally relying on the presence of null collection elements in your ValueSerialiser implementation, your code's behavior may be affected.
• Since 1.3.0-M1: MissingValueException is now correctly thrown in the case where it should be thrown (MissingKeyException used to be thrown instead).

1.3.0-M2: Fixed Support for SnakeYaml Versions

This release fixes and officializes DazzleConf's support for SnakeYaml versions 1.15 through 1.33, and 2.0+. You may now use dazzleconf-ext-snakeyaml with any of these SnakeYaml versions.

There are no changes to the core library or the other configuration formats.

1.3.0-M1: Improved Errors and User-Facing Messages

This release is in honor of the 1-year anniversary of DazzleConf's first deployment to Maven Central.

Compared to 1.2.0, where much was done, 1.3.0 has far less upheaval. The planned features for 1.3.0 are described by this milestone.

Additions:

• Significantly improved error messages:
  • Messages have been clarified and detail added to them.
  • Examples of correct user input are given.
• Added a few methods accepting CharSequence for exception messages, to reduce boilerplate.

Fixes:

• Null elements are prohibited in lists, sets, collections, and maps. Previously, it was possible in some cases to access these null elements, and, through ValueSerialiser, to deserialize them as some other type. #23
• In previous versions, MissingKeyException was thrown where MissingValueException should have been thrown. This is now corrected.

Migration from 1.2.x:

• Null collection elements are now (correctly) prohibited. If you were accidentally relying on the presence of null collection elements in your ValueSerialiser implementation, your code's behavior may be affected.
• MissingValueException is now correctly thrown in the case where it should be thrown (MissingKeyException used to be thrown instead).

1.2.1: Bug Fixes and Test Coverage Improvements

Fixes:

• DazzleConf-SnakeYaml does not fail on non-string keys.
• The status of whether auxiliary keys were used (indicated by the AuxiliaryKeys interface marker) is now accurate in the case that a sub-section was used. This is quite important considering ConfigurationHelper relies on the status of whether auxiliary values were used to determine whether to rewrite the configuration with the latest keys.
• In very rare circumstances using conflicting dotted key paths, clear error messages rather than internal exceptions are thrown.

Other:

• Clarified the documentation of FlexibleType in a few places.
• Test coverage requirement of 75%, according to PITest's mutation test coverage.

Migration:

• Some rare issues when using conflicting dotted key paths previously resulted in internal exceptions. They now throw correct exceptions.
• In the past, ConfigurationHelper may have rewritten the configuration in more cases than it should have. This might have caused comments to update in the case where they weren't supposed to be updated. This will no longer happen.

1.2.0: Promotion of 1.2.0-RC1 to Full Release

1.2.0-RC1 has been released for one month now, and before it, 1.2.0-M2 had been released with very few differences. Time has passed and projects have upgraded successfully to 1.2.0-RC1. With this release, the new APIs tested in the past months become considered fully stabilized.

The below lists catalog all cumulative changes since 1.1.x. This is the same changelog as for RC1, with the exception of dbaa4de, a minor bugfix, being the only difference between 1.2.0 and 1.2.0-RC1.

---

Additions:

• Hocon format support:
  • Use HoconConfigurationFactory.create
  • Use the artifact dazzleconf-ext-hocon
  • Depends on lightbend/config
• Better comment support for SnakeYaml. There are now 3 comment modes you can use:
  • CommentMode.headerOnly - existing default behavior. Only writes the comment header.
  • CommentMode.alternativeWriter - existing optional behavior formerly provided by useCommentingWriter(true). This used to be the only way to write comments with snakeyaml.
  • CommentMode.fullComments - the most interesting. It uses SnakeYaml 1.28's new capability of writing comments. If you want to use this mode, you need to use SnakeYaml 1.28 or later.
• Allow complex default objects via @DefaultObject. For example, if you had a Map<String, YourCustomType> in your config, it was not possible in 1.1.x to provide a default value without this feature.
• @SubSection has been greatly improved and is complimented by features of@DefaultObject:
  • @SubSection can now be used on Map values and Collection elements.
  • When implementing a @DefaultObject method for a config entry returning a Map<String, @SubSection MySection> or Collection<@SubSection MySection>, you can optionally declare a single parameter which is the default value of the section.
  • Here is an example show-casing these features:

@DefaultObject("sectionsSetDefaults")
Set<@SubSection MySection> sectionsSet();

static Set<@SubSection MySection> sectionsSetDefaults(MySection defaultMySection /* optional param */) {
	return Set.of(defaultMySection);
}

Changes:

• Some error messages have been improved.
• Access checking is better pre-empted when using JPMS.
• For GsonConfigurationFactory, html escaping is now disabled in the Gson instance by default (this change is fully compatible with existing configurations).

Fixes:

• Static methods in config interfaces are allowed.
• Document that no non-deprecated API methods exist which return null
• Clarify that builder.build() methods are free of side-effects

Migration from 1.1.x - Deprecations:

• The SnakeYamlConfigurationFactory and GsonConfigurationFactory constructors have been deprecated. Use the static create methods for new code.
• SnakeYamlOptions#useCommentingWriter has been deprecated. Use #commentMode with CommentMode.alternateWriter instead.
• AbstractConfigurationFactory and BaseConfigurationFactory are deprecated. Relevant for anyone who wrote their own format support.
• ConfigurationOptions#getSorter and ValueSerialiserMap#getSerialiser, which returned null, have been deprecated in favor of #getConfigurationSorter and #getSerialiserFor, which return Optional

Migration from 1.2.0-M1:

• SnakeYamlOptions#commentFormat has been removed. Use the #commentMode method instead.

Migration from 1.2.0-SNAPSHOT:

• See release notes for 1.2.0-M1

1.2.0-RC1: Promotion of 1.2.0-M2 to Stable

1.2.0-M2 has been released for some time and no bugs have been found when upgrading projects to it. As such, it is promoted to a release candidate.

The below lists catalog all cumulative changes since 1.1.x.

Additions:

• Hocon format support:
  • Use HoconConfigurationFactory.create
  • Use the artifact dazzleconf-ext-hocon
  • Depends on lightbend/config
• Better comment support for SnakeYaml. There are now 3 comment modes you can use:
  • CommentMode.headerOnly - existing default behavior. Only writes the comment header.
  • CommentMode.alternativeWriter - existing optional behavior formerly provided by useCommentingWriter(true). This used to be the only way to write comments with snakeyaml.
  • CommentMode.fullComments - the most interesting. It uses SnakeYaml 1.28's new capability of writing comments. If you want to use this mode, you need to use SnakeYaml 1.28 or later.
• Allow complex default objects via @DefaultObject. For example, if you had a Map<String, YourCustomType> in your config, it was not possible in 1.1.x to provide a default value without this feature.
• @SubSection has been greatly improved and is complimented by features of@DefaultObject:
  • @SubSection can now be used on Map values and Collection elements.
  • When implementing a @DefaultObject method for a config entry returning a Map<String, @SubSection MySection> or Collection<@SubSection MySection>, you can optionally declare a single parameter which is the default value of the section.
  • Here is an example show-casing these features:

@DefaultObject("sectionsSetDefaults")
Set<@SubSection MySection> sectionsSet();

static Set<@SubSection MySection> sectionsSetDefaults(MySection defaultMySection /* optional param */) {
	return Set.of(defaultMySection);
}

Changes:

• Some error messages have been improved.
• Access checking is better pre-empted when using JPMS.
• For GsonConfigurationFactory, html escaping is now disabled in the Gson instance by default (this change is fully compatible with existing configurations).

Fixes:

• Static methods in config interfaces are allowed.
• Document that no non-deprecated API methods exist which return null
• Clarify that builder.build() methods are free of side-effects

Migration from 1.1.x - Deprecations:

• The SnakeYamlConfigurationFactory and GsonConfigurationFactory constructors have been deprecated. Use the static create methods for new code.
• SnakeYamlOptions#useCommentingWriter has been deprecated. Use #commentMode with CommentMode.alternateWriter instead.
• AbstractConfigurationFactory and BaseConfigurationFactory are deprecated. Relevant for anyone who wrote their own format support.
• ConfigurationOptions#getSorter and ValueSerialiserMap#getSerialiser, which returned null, have been deprecated in favor of #getConfigurationSorter and #getSerialiserFor, which return Optional

Migration from 1.2.0-M1:

• SnakeYamlOptions#commentFormat has been removed. Use the #commentMode method instead.

Migration from 1.2.0-SNAPSHOT:

• See release notes for 1.2.0-M1

1.2.0-M2: Hocon Support, Better Yaml Comments, Bugs Fixed From M1

With this release comes hocon support and more comment handling options with yaml. It also includes several bug-fixes for sub-section collections, a feature which should be stabilized by this release.

Additions:

• Hocon format support via HoconConfigurationFactory. Use the artifact dazzleconf-ext-hocon.
• Better comment support for SnakeYaml. There are now 3 comment modes you can use:
  • CommentMode.headerOnly - existing default behavior. Only writes the comment header.
  • CommentMode.alternativeWriter - existing optional behavior formerly provided by useCommentingWriter(true). This used to be the only way to write comments with snakeyaml.
  • CommentMode.fullComments - the most interesting. It uses SnakeYaml 1.28's new capability of writing comments. If you want to use this mode, you need to use SnakeYaml 1.28 or later.

Fixes:

• Sets and Collections of sub-sections are now permitted properly.
• Fixed SnakeYamlConfigurationFactory when using the alternate writer and a list of sub-sections. Resulted in IllegalArgumentException: Unknown single value type class java.util.LinkedHashMap
• Restored behavioral compatibility with 1.1.x when auxiliary values are used and an entry is missing

Migration from 1.2.0-M1:

• SnakeYamlOptions#commentFormat has been removed. Use the #commentMode method instead.
• SnakeYamlOptions#useCommentingWriter has been deprecated. Use #commentMode with CommentMode.alternateWriter instead.
• An example for both migrations:

SnakeYamlOptions yamlOptions = new SnakeYamlOptions.Builder().commentMode(CommentMode.alternativeWriter(" # %s")).build();

As always, releases are available on Maven Central. This is a milestone release.

1.2.0-M1: SubSection Improvements

With this release comes several changes.

Additions:

• @SubSection can now be used on Map values and Collection elements.
• When implementing a @DefaultObject method for a config entry returning a Map<String, @SubSection MySection> or Collection<@SubSection MySection>, you can optionally declare a single parameter which is the default value of the section.
• If the target method of @DefaultObject is in the same class as the config interface, you can omit the class name and simply use the method name.
  Here is an example show-casing all 3 features:

@DefaultObject("com.mypackage.ConfigDefaults.sectionsMapDefaults")
Map<String, @SubSection MySection> sectionsMap();

@DefaultObject("sectionsSetDefaults")
Set<@SubSection MySection> sectionsSet();

static Set<@SubSection MySection> sectionsSetDefaults(MySection defaultMySection /* optional param */) {
	return Set.of(defaultMySection);
}

Changes:

• The SnakeYamlConfigurationFactory and GsonConfigurationFactory constructors have been deprecated. Use the static create methods for new code.
• Some error messages have been improved. Accessibility checking is better pre-empted when using JPMS.
• AbstractConfigurationFactory and BaseConfigurationFactory are deprecated. Relevant for anyone who wrote their own format support.

Fixes:

• Equality of configuration implementations is solved.
• Empty configuration streams are handled correctly.
• Static methods in config interfaces are allowed.
• Location of the Class in which the method specified by @DefaultObject resides now uses the classloader of the config class, as opposed to the classloader which loaded the library classes. This fixes setups where DazzleConf is in a parent classloader. (Bug from 1.2.0-SNAPSHOT)

Migration from 1.2.0-SNAPSHOT:

• @DefaultObject could theoretically have been used to return primitive values and strings. This is no longer allowed.
• Objects returned from @DefaultObject methods had type conversion performed on them. This is no longer the case. Now, any object returned from such a method must be an instance of the target type.

To support the feature of sub-sections as collection elements and map values, somewhat significant refactoring was necessary. Please note if you find any edge cases which differ between this release and past versions. This is a milestone release.