Configurate v4.0.0 Release Notes

Release Date: 2020-11-14 // 11 months ago
  • 🚀 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
    • 0️⃣ 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)

Previous changes from 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