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
TypeSerializer
s forPath
andFile
- โ Added new
registerExact
method toTypeSerializerCollection.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 betweenCodec
s andTypeSerializer
s. - ๐ 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
extendsIOException
, 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
TypeSerializer
s. This will, for collection types, resolvenull
node values as empty collections. Implicit initialization is enabled by default.
๐ฅ Breaking changes
- ๐ฆ Moved from
ninja.leaping
toorg.spongepowered
package. - ๐ฆ Moved type serializers from
objectmapping.serialize
toserialize
package. - ๐ฆ Made node implementation classes package-private, and moved the attributed and commented node subtypes out of their own packages.
- โฌ๏ธ Dropped the
get
andset
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 eitherjava.lang.reflect.Type
or the GeAnTyRefTypeToken
. - ๐ง Renamed
configurate-json
implementation toconfigurate-jackson
. - ๐ง Renamed
configurate-ext-kotlin
toconfigurate-extra-kotlin
. - ๐ง Moved Guice support out of
core
intoconfigurate-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 returnsCommentedConfigurationNode
instances, in preparation for full comment support coming in a future release. - ๐ง In the
YAML
andHOCON
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 forshouldCopyDefaults
has been set totrue
. - ๐ 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, Kotlindata
classes.
The@Setting
annotation is now optional. By default, all non-transient fields will be included in objects, and names will be converted to thekebab-case
naming scheme. Both of these can be customized with a customObjectMapper.Factory
- 0๏ธโฃ The
shouldCopyDefaults
option is now respected for mapped object fields. - ๐ The
ObjectMapperFactory
field has been removed fromConfigurationOptions
. Instead, the object mapper can be registered like any other type serializer, using theTypeSerializerCollection.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)
- โ Added
-
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 theconfigurate-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 inConfigurationOptions
have been deprecated, to be replaced with equivalent methods starting withwith___
. - Accessors in
TypeSerializers
have been moved toTypeSerializerCollection
, andregister ____
methods have been renamed toregister
- ๐ง 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 withConfigurationNode.appendListNode()
hasListChildren()
andhasMapChildren()
should be replaced withisList()
andisMap()
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 structuredConfigurationVisitor
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
TypeSerializer
s for arrays,char
s,Set
s, andConfigurationNode
score: 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 aConsumer<ConfigurationNode>
to perform an action on the nodecore: New
setCommentIfAbsent
method onCommentedConfigurationNode
score: Abstract
TypeSerializer
implementations added forScalar
s and objects read from list nodes๐ loader: Added functional helper methods for changing options and options'
TypeSerializerCollection
when building a loadercore: New
getNode(Iterable<?>)
method will work the same asgetNode(Object...)
, but allow looking up nodes without having to convert existing collections to arrays.core:
AttributedConfigurationNode
now extendsCommentedConfigurationNode
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
Map
s - ๐ง 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 acceptTypeToken
s 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 ofNumber
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. - ๐ง All
-
v3.6.1 Changes
May 31, 2019๐ 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
ConfigurationNode
s 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
andConfigurationTransformation
- ๐ง Revert compatibility break with
-
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
inConfigurationNode#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'
becomes
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