All Versions
Latest Version
Avg Release Cycle
167 days
Latest Release
1290 days ago

Changelog History

  • v4.0.0 Changes

    November 14, 2020

    ๐Ÿš€ 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)
  • v3.7.2 Changes

    November 05, 2020

    ๐Ÿ›  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

  • v3.7.1 Changes

    August 10, 2020

    ๐Ÿ›  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).
  • v3.7 Changes

    May 26, 2020

    ๐Ÿš€ 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! 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.

  • v3.6.1 Changes

    May 31, 2019

    ๐Ÿ› Bug fixes following the 3.6 release:

    ๐Ÿ›  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.

  • v3.5 Changes

    June 26, 2018
    • ๐Ÿ”ง Revert compatibility break with NodePath and ConfigurationTransformation
  • v3.4 Changes

    June 25, 2018
    • ๐Ÿ›  Fix this bug: Lists in config get set to null
    • ๐Ÿ”ฆ Expose customized default render and parse options
    • ๐Ÿ›  Fix reading of multi-line HOCON comments
    • Select from available type serializers in the order they were added
    • ๐Ÿ”„ change group to org.spongepowered
    • ๐Ÿ”ง Implement XML configuration loader
    • Invalidate cached type matches when a new serializer is added
    • โž• Add ConfigurationNode#copy
    • ๐Ÿ”ง Only include the key + value in ConfigurationNode#toString
    • ๐Ÿ›  Fix CommentedConfigurationNode#equals never returning true
    • ๐Ÿ”ง Implement NodeWalker utility for traversing configuration structures
    • ๐Ÿ›  Fix compatibility with older versions of guava

    Migration Note:

    โšก๏ธ As the gradle group has changed from ninja.leaping to org.spongepowered you will need to update your dependencies in your build scripts.

    E.g. For Gradle:

        compile 'ninja.leaping.configurate:configurate-hocon:3.3'
        compile 'ninja.leaping.configurate:configurate-gson:3.3'
        compile 'ninja.leaping.configurate:configurate-yaml:3.3'


        compile 'org.spongepowered:configurate-hocon:3.4'
        compile 'org.spongepowered:configurate-gson:3.4'
        compile 'org.spongepowered:configurate-yaml:3.4'
        compile 'org.spongepowered:configurate-xml:3.4'

    No other changes should be necessary.

  • v3.3 Changes

    May 13, 2017
    • โšก๏ธ Update Maven and various Maven plugins
    • โšก๏ธ Update snakeyaml to 1.18 from 1.16, jackson to 2.8.8 from 2.6.3, typesafe hocon config to 1.3.1 from 1.3.0, gson to 2.8.0 from 2.2.4, and optional guice dependency to 4.1 from 4.0 where used.
    • โšก๏ธ Move usage of removed Guava method, update Guava
    • Resolve some issues with atomic writes by using more fine-grained time when generating temp file names
    • ๐Ÿ‘ Allow resolving enums that don't follow standard naming conventions. Lookup is case-insensitive and ignores underscores. If the enum has two fields that are equal except for case and underscores, an exact match will return the appropriate value, and any fuzzy matches will map to the first value in the enum that is applicable.

    ๐Ÿ”ง Downloads are available from Maven Central

  • v3.2 Changes

    October 04, 2016
    • ๐Ÿ‘ Allow Gson module to save empty files
    • ๐Ÿ”ง Resolve configuration variables for hocon
    • ๐Ÿ›  Fix various issues on Windows
    • Correct file permissions
    • ๐Ÿ‘Œ Improve error message when unable to find an appropriate TypeSerializer or when using raw types
    • ๐Ÿ‘ Allow stripping header from files entirely