Configurate v4.2.0

At long last, Configurate 4.2.0 is here. This release offers a variety of smaller features and fixes, please see below for a full listing. Thank you for your patience -- hopefully we have some bigger things to offer in the near future.

(you didn't see any mistakes in the publishing of this release)

what's changed

core

• 06c4e3c - Fix list value cannot be de-serialized (#421)
• 2ed493f - fix(core): Pass through exceptions from TypeSerializers
• 621e791 - fix(core): Be stricter about implicitly creating list nodes
• 169bbdc - feat(core): Add TypeSerializer for Optional
• 8c35fd3 - core: Add new PatternFlags annotation to modify the Pattern serializer
• 0edfdcf - core: Box when setting values with a Type
• b448919 - core: Correct documentation on BooleanSerializer for 4.0.0 changes
• 48dd2c8 - core: Allow type serializers to work with annotated types (#296)
• 66092f4 - core: Add an object discoverer for only instantiable objects
• 255c724 - core: Allow building empty transformations
• ea956f5 - core: Add support for object mapper post-processing (#294)
• 1333c96 - Add a LoaderOptionSource to configure loaders (#215)
• 3c48e84 - core: Handle interaction of implicit initialization and default values
• b8df03e - core: Actually stop trying to write files when successful
• 49575dd - core: Correct javadoc in ConfigurationOptions for implicit init option
• fa4ccd1 - Fix getString serialization. (#245)
• 1392ef7 - Remove some erroneous nullable annotations from ConfigurationNode (#217)

hocon

• 41dc9e4 - fix(hocon): out of bounds exception with empty comment line (#451)
• 458466c - hocon: fix round-tripping of extraneous comment indent (#449)
• 4d58ce3 - hocon: Add option for indent level (#448)
• 53201ee - hocon: setup vendor project, remove config sorting on write and use order preserving collections (#446)

yaml

• f8bb158 - yaml: Move to bundled patched copy of SnakeYAML
• 5e745c3 - fix(snakeyaml): Avoid emitting unnecessary whitespace with comments

extra-kotlin

• 3ad6a69 - Add Kotlin extensions and helpers around ObjectMapper and Processors (#409)

extra-dfu4

• 859aec5 - extra-dfu4: Add cross-compatibility with SLF4J-using versions of DFU

tooling changes

• 352310e - build: Publish javadoc to Sponge-wide index
• a9becef - build: Fix aggregate javadoc exclusions (#205)

New Contributors

• @kezz made their first contribution in #205
• @Lignium made their first contribution in #217
• @portlek made their first contribution in #245
• @Machine-Maker made their first contribution in #353
• @DenWav made their first contribution in #409
• @Karlatemp made their first contribution in #421
• @powercasgamer made their first contribution in #532

Full Changelog: 4.1.2...4.2.0

Configurate v4.1.2

• core: Fix conversion of zero-value doubles to floats (#206)
• core: Optimize TypeSerializerCollection.get based on end-user profiling
• core: Fail fast when values of an incorrect type are set (#210)

Configurate v3.7.3

• Add Automatic-Module-Name manifest attribute to all Configurate components. This allows the 3.x series to be used in a modular environment.

Note: The module names were selected to align with the Configurate 4 artifact (and module) names. See the 4.0.0 release notes for information on the module renames that happened for that release.

Configurate v4.1.1

• Hotfix: Restore ability to write to final fields with the object mapper (#200)

Configurate v4.1.0

This is a minor feature release to the Configurate v4 series that addresses a variety of bugfixes, small API additions, and Javadoc tweaks that have built up in the months since the 4.0.0 release.

Thanks to forresthopkinsa, jpenilla, and ItsTehBrian for their contributions to this release.

Added

• core: NodePath.plus added to combine paths
• core: AbstractListChildSerializer is now part of Configurate's public API
• core: Added methods on ConfigurationLoader to load/save from strings
• core: Temporary files for writing are now prepended with a . so they appear hidden in file viewers
• core: Multi-release jar functionality is now used to take advantage of some collections and reflection API only available in newer Java versions
• core: Added analysis annotations to indicate contracts in ConfigurationOptions and AbstractConfigurationLoader
• core: Added ConfigurationNode.require methods for cases where a return value is known to be non-null, to avoid nullabilty warnings in IDEs
• core: Added flags field to the @Matches constrant annotation to pass through Pattern flags
• gson: Added serializers for JsonElement and its subtypes (accessible via GsonConfigurationLoader.gsonSerializers())
• kotlin: Add supplier-defaulted get() extensions to ConfigurationNode

Fixed

• core: Retry closing in AtomicFiles, to attempt better handling of Windows file locking
• core: Handling of integer keys in the map serializer (#184)
• core: Improve error messages when trying to get the object mapper to construct an object instance that it is unable to.
• core: Fix handling of absent primitive fields in the record object mapper
• core: Fix erasing target files when attempting to save a clearly invalid node (#189)
• core: Sets of enums are now deserialized as EnumSets rather than HashSets
• core: Add missing primitive types to Types.box/unbox
• core: Separate the concepts of a null value and being virtual, to correct handling of null-valued non-virtual nodes (#187)
• core: Correctly handle configuration files stored within symlinked directories
• core: Fixed improper floating-point precision testing (#198)
• hocon: Ensure leading spaces in comments are stripped
• kotlin: Correct the non-defaulted get method to use the appropriate Java overload of get (#185)

Deprecated

• kotlin: The NodePath.plus extension function has been deprecated since it is replaced by the plus method in NodePath itself.

Configurate v4.0.0

Welcome to a new major release of Configurate! We've taken the time to review a lot of longstanding pain points, so there are a variety of breaking changes in this release. Some of the behaviour changes can be subtle, so please read the changelog carefully.

To ease upgrading for IntelliJ users, a migration XML file has been attached to this release. This can be imported as IDE settings, or placed in your $INTELLIJ_HOME/migration folder (in %APPDATA%/Roaming/JetBrains on Windows).

New features

• Added TypeSerializers for Path and File
• Added new registerExact method to TypeSerializerCollection.Builder to register serializers for only a single type and not its subtypes.
• Added Java 14+ record support and many other features to the object mapper (see below for more details).
• Added new submodules to integrate with Mojang's DataFixerUpper library (versions 2-4), with a DynamicOps implementation, DataFix-using transformations, and conversions between Codecs and TypeSerializers.
• Make more extensive use of a unified NodePath across the whole API, for operations like resolving nodes and specifying transformation paths.
• Redesigned the exception structure of the project, so all configuration operations throw exceptions that extend from ConfigurateException, which provide more machine-readable metadata. ConfigurateException extends IOException, so existing error handling may not break.
• Add new NodeFactory interface to provide a common view for creating configuration nodes.
• Limited support for reading YAML files indented with tabs.
• Added a new "representation hints" system for attaching arbitrary metadata to nodes.
• Added support for "implicit initialization" in TypeSerializers. This will, for collection types, resolve null node values as empty collections. Implicit initialization is enabled by default.

Breaking changes

• Moved from ninja.leaping to org.spongepowered package.
• Moved type serializers from objectmapping.serialize to serialize package.
• Made node implementation classes package-private, and moved the attributed and commented node subtypes out of their own packages.
• Dropped the get and set prefixes from method names across the API.
• No longer depends on the Guava library. This has resulted in a lot of code that formerly used the Guava TypeToken moving to use either java.lang.reflect.Type or the GeAnTyRef TypeToken.
• Renamed configurate-json implementation to configurate-jackson.
• Renamed configurate-ext-kotlin to configurate-extra-kotlin.
• Moved Guice support out of core into configurate-extra-guice.
• When loading a configuration file, empty lists and maps are represented as such in nodes in all loaders. In the past, some loaders have provided null values instead.
• YamlConfigurationLoader now returns CommentedConfigurationNode instances, in preparation for full comment support coming in a future release.
• In the YAML and HOCON loaders, the underlying libraries used are now to be treated as an implementation detail. All API that directly referenced them has been replaced with equivalents that use Configurate types.
• The default ConfigurationOptions values for shouldCopyDefaults has been set to true.
• The deprecated node walker has been removed.

Object Mapper

The object mapper has changed quite a bit, so most users will need to change their use in some way.

• Refactored TypeSerializerCollection to be immutable. A new child collection must be created to add custom type serializers.
• Redesigned the object mapper to be more extensible. Rather than subclassing the object mapper as some people did before, there are now defined extension points where additional annotations and behaviours can be registered. See the methods in ObjectMapper.Factory.Builder for a more thorough overview.
• Added support for Java 14+ records and, in combination with the configurate-extra-kotlin module, Kotlin data classes.
  The @Setting annotation is now optional. By default, all non-transient fields will be included in objects, and names will be converted to the kebab-case naming scheme. Both of these can be customized with a custom ObjectMapper.Factory
• The shouldCopyDefaults option is now respected for mapped object fields.
• The ObjectMapperFactory field has been removed from ConfigurationOptions. Instead, the object mapper can be registered like any other type serializer, using the TypeSerializerCollection.Builder#registerAnnotatedObjects method.

Bugs fixed

• Create the parent directory of files being written, to remove a common 'gotcha'.
• Try to group together events in the watch service listener, to reduce duplicate reloads.
• Fix merging values into a virtual node not correctly attaching the node (#181)

Configurate v3.7.2

This is a bugfix release for the Configurate 3.7 series, coming with a few minor fixes:

• Work around null values appearing when visiting configuration nodes
• Be more defensive when potentially returning null lists

Compiled jars are available from Maven Central

Configurate v3.7.1

This is a bugfix release for 3.7, coming with a few minor tweaks:

• Fix saving JSON-format configurations starting from a non-root node (#163)
• Correctly handle removing a never-attached list element from its parent node
• Follow symbolic links when saving using AtomicFiles (default for most configuration loaders).

Configurate v3.7

After a long wait, v3.7 is finally here. The biggest feature in this release is the ConfigurationReference system and associated ability to automatically reload configurations, but it also contains a variety of bug fixes and deprecates some methods in preparation for 4.0. There is now also a collection of idiomatic Configurate examples included in the repository, under the configurate-examples folder that can be referenced for inspiration on how to effectively use the library.

Additionally, up-to-data Javadocs are now published at https://configurate.aoeu.xyz! It's been a while since javadocs were last updated, so the new revision brings a lot of improvements.

Thanks to @kashike for contributions to this release

Deprecations

• All set* methods in ConfigurationOptions have been deprecated, to be replaced with equivalent methods starting with with___.
• Accessors in TypeSerializers have been moved to TypeSerializerCollection, and register____ methods have been renamed to register
• Modifying the global TypeSerializerCollection is deprecated behaviour. Any configurations that need custom type serializers should create their own child of the default collection and add to that.
• ConfigurationNode.getAppendedChild() should be replaced with ConfigurationNode.appendListNode()
• hasListChildren() and hasMapChildren() should be replaced with isList() and isMap() to more effectively express that they reflect the type of the node, not whether it has contents.
• As root node creation methods have been moved to the node interface, usage of the Simple* nod implementation classes is deprecated. They will be made package-private in 4.0.
• ConfigurationNodeWalker has been deprecated, to be replaced with the new more structured ConfigurationVisitor API.
• ValueType will be removed in 4.0. Its functionality is already covered by existing methods.

Added

• New configuration and value reference system for automatically reloading configurations

• New module configurate-ext-kotlin with some basic utilities for using Configurate in Kotlin

• New module configurate-tool is a CLI tool to inspect configurations loaded through Configurate loaders`

• New module: configurate-bom can be imported to centralize Configurate version declaration across a project

• loader: Automatically create parent directories when trying to write a configuration

• objectmapping: New TypeSerializers for arrays, chars, Sets, and ConfigurationNodes

• core: New method isEmpty() to determine if a node has contents, or exists but with an empty value.

• core: New act method on nodes that takes a Consumer<ConfigurationNode> to perform an action on the node

• core: New setCommentIfAbsent method on CommentedConfigurationNodes

• core: Abstract TypeSerializer implementations added for Scalars and objects read from list nodes

• loader: Added functional helper methods for changing options and options' TypeSerializerCollection when building a loader

• core: New getNode(Iterable<?>) method will work the same as getNode(Object...), but allow looking up nodes without having to convert existing collections to arrays.

• core: AttributedConfigurationNode now extends CommentedConfigurationNode

• xml: Load and save comments

• all: Configurate jars now include their license for easier compliance

Fixed

• objectmapping: Preserve comments on map keys when round-tripping data through the type serializer for Maps
• gson: Correctly ignore null values in JSON files loaded from the Gson configuration loader
• objectmapping: Resolve type parameters in fields. For example, in a class class MyConfig<T> { @Setting private List<T> items;, the list will be appropriately resolved as long as new object mapper factory methods that accept TypeTokens are used.
• objectmapping: Correctly reject interface types from being passed to ObjectMappers rather than throwing an exception
• objectmapping: Preserve configuration options when deserializing map keys
• hocon: Read empty lists as empty lists, to match behaviour when reading maps.
• loader: Don't read whole line to determine if file contains header. Resolves issues exceeding the mark limit on extremely long first lines, or files without line breaks (minified JSON, for example)
• objectmapping: The TypeSerializer for subclasses of Number will now attempt to coerce values to types native to the destination configuration when serializing.
• core: AttributedConfigurationNodes will now be attached as soon as attributes are set on them.
• core: The root configuration node's path is the empty array, and getPath() has been corrected to return this.

Releases are available on the Sponge maven repo, and all configurate components are contained within the configurate-tool distribution attached to this release.

3.6.1

Bug fixes following the 3.6 release:

• Invalid TypeSerializer registration for arbitrary Number classes
• Fix merging overwriting non-null values with null values

This bugfix release does not change any previous behaviors of serialization/deserialization, except now merging ConfigurationNodes will no longer null values from the other node being merged into the parent if the parent has a null value in said node.