The work on this software project is in no way associated with my employer nor with the role I'm having at my employer. Any requests for changes will be decided upon exclusively by myself based on my personal preferences. I maintain this project as much or as little as my spare time permits.
Alternative to the JDK class java.util.Properties.
The provided class nu.studer.java.util.OrderedProperties fixes the design flaw of using
inheritance over composition, while keeping up the same APIs as the original class. In contrary
to the original implementation, keys and values are guaranteed to always be of type String.
As additional functionality, the properties are read, stored, and iterated in a well-defined order. Also, an option is provided to omit the current date from being persisted as a comment in the specified properties file.
The java-ordered-properties dependency is hosted at Maven Central and at Bintray's JCenter.
Recent build scan: https://gradle.com/s/neny3ulp4s3mc
Find out more about build scans for Gradle and Maven at https://scans.gradle.com.
The goals of the class nu.studer.java.util.OrderedProperties are the following:
- Provide a non-obstructed API by using composition over inheritance
- Ensure all APIs operate exclusively on keys and values of type
java.lang.String - Allow to iterate over the properties read in from a properties file in the same order they are listed in the file
- Allow to store the properties to a properties file in the same order they were added or read in
- Make it possible to customize the ordering strategy of the properties
- Offer a flag to omit the current date from being stored as a comment in the properties file
- Delegate all file read / write logic to the original implementation
All functionality is fully encapsulated in the single class nu.studer.java.util.OrderedProperties.
The class nu.studer.java.util.OrderedProperties extends directly from java.lang.Object. It keeps its
own java.util.Map of the properties it manages. The ordering of the properties by their keys can be customized
through a java.util.Comparator instance. Filtering out the current date from being stored to the properties file
is achieved by a decorating java.io.BufferedWriter. Reading properties to and from a file is delegated to the
java.util.Properties class since the involved logic is quite complex and code duplication is not desired.
The class nu.studer.java.util.OrderedProperties implements equals and hashCode based on the properties
and the order in which they appear. The class also fulfills the contract of java.io.Serializable.
The class nu.studer.java.util.OrderedProperties does not rely on any third-party dependencies.
Use the already existing functionality by instantiating the class nu.studer.java.util.OrderedProperties and
use its APIs to set, get, iterate, persist, and load properties the same way it is done with the API of the
class java.util.Properties.
OrderedProperties properties = new OrderedProperties();
properties.load(new FileInputStream(new File("~/some.properties")));
String value = properties.getProperty("someKey", "someDefaultValue");You can also test for the presence of a given property, and remove a given property.
boolean isPresent = properties.containsProperty("someKey");
String value = properties.removeProperty("someKey");Use the new functionality by instantiating the builder class nu.studer.java.util.OrderedProperties.OrderedPropertiesBuilder. You
can then configure the builder accordingly to use a custom ordering and to omit the current date in the properties file.
OrderedPropertiesBuilder builder = new OrderedPropertiesBuilder();
builder.withOrdering(String.CASE_INSENSITIVE_ORDER);
builder.withSuppressDateInComment(true);
OrderedProperties properties = builder.build();An instance of nu.studer.java.util.OrderedProperties can be copied into a new instance through a static factory method.
OrderedProperties copy = OrderedProperties.copyOf(sourceOrderedProperties);If needed for compatibility with existing APIs that consume JDK properties, an instance of
nu.studer.java.util.OrderedProperties can be converted to an instance of java.util.Properties.
OrderedProperties properties = new OrderedProperties();
properties.setProperty("someKey", "someValue");
java.util.Properties jdkProperties = properties.toJdkProperties();The class nu.studer.java.util.OrderedProperties has been tested to work on Java 8 and higher. See
the GitHub Actions script
for the complete set of covered Java versions.
Both feedback and contributions are very welcome.
- joschi (issue #4 that surfaces a problem with escaping of non-latin characters)
This class is available under the Apache License, Version 2.0.
(c) by Etienne Studer