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.

1.1.1 - Minor Fixes

This release brings 2 bug-fixes to the 1.1.x series:

• Fixed equality of generated proxies
• Fixed handling of empty configuration streams (e.g. empty config files)

For users who are already on 1.2.0-SNAPSHOT, a 1.2.0-M1 release with support for sub-sections in collections is coming soon.

1.1.0 - Added ConfigurationHelper

Changes:

• Validate return types are public, a requirement for dynamic proxies.
• Javadoc no longer includes internal packages.
• Added ConfigurationHelper, which solves much boilerplate

Releases are deployed directly to Maven Central. As such, binaries will not be uploaded here.

ConfigurationHelper

This release includes the ConfigurationHelper which is noted on the "Configuration Manager" wiki page