Repository files navigation

Java Properties is a drop-in replacement of the ubiquitousjava.util.Propertiesthat everybody knows and loves (hates?).

It's an alternative implementation whose most important advantage over its standard Java sibling is thatit fully supports comments in inputand output.

Meaning that a properties table like this can not only be read, but also created, changedand be written back without losing any of the comments or formatting.

# Server configuration file# Host name for remote serverremoteHost=myserver.example.com# Port numberremotePort=8080# Password hash algorithm to use# (choose between MD5, SHA256 or SHA512)passwordHash=SHA512

Add it to your build file with:

<dependency>    <groupId>org.codejive</groupId>    <artifactId>java-properties</artifactId>    <version>0.0.6</version></dependency>

or

implementation'org.codejive:java-properties:0.0.6'

And add this import to your code:

importorg.codejive.properties.Properties;

After which you can do something like:

Propertiesp =newProperties();p.setProperty("port","8080");p.setComment("port","Port number to use for the server");

or just directly in a single line:

Propertiesp =newProperties();p.setProperty("port","8080","Port number to use for the server");

And if you would write this out:

p.store(System.out)

you'll get:

# Port number to use for the serverport=8080

You can also set multi-line comments simply like this:

p.setComment("port","Port number to","use for the server");p.setProperty("port","8080","Port number to","use for the server");

which would both result in:

# Port number to# use for the serverport=8080

Retrieving values is simple:

p.get("port");// Returns "8080"p.getProperty("port");// Also returns "8080"p.getComment("port")// Returns ["# Port number to", "# use for the server"]

Just like with the originalProperties implementation, lines starting with a# or a! are considered comments. Consecutive comments lines (even the onesthat start with another comment character) and have no other lines in between(not even empty lines) are considered a single multi-line comment.

# A single comment line! A multi-line comment! spanning two lines# This is also a multi-line comment! but using different comment charstwo=Second value

Comments are considered either "free" or "attached", which you could see as either beingjust part of the file or attached to a property. For example:

# A header comment (free)one=First value (that has no comment)! Another free comment# An attached commenttwo=Second value

Any comments that directly precede a property, so no empty lines in between, are considered"attached" to that property, which also means the comment can be retrieved usingprops.getComment(key).On the other hand "free" comments are not attached to anything and there's no way to retrieve theirvalues except when they are written out usingstore() orlist().

This is also the reason that, when usingstore() with a comment, eg.props.store(out, "The first line"),it will actually insert an empty line after that comment, so it won't be considered attached tothe first property.

Another thing to take into account is that when retrieving comment, by usinggetComment(key), you'll get alist of strings that will include the comment character. So, for example in the table above, runninggetComment("two") will return"# An attached comment".

In the same way, when setting comments, either by usingsetComment(key, comment) orsetProperty(key, value, comment), the comment lines are expected to start with a comment character.Fortunately, it isn't an error to pass in lines that do not start with a comment character and the code willtry its best to figure out what comment character to use and prepend that to the lines.

Theorg.codejive.Properties class is mostly a drop-in replacement ofjava.util.Properties with onlya couple of differences:

• the API now usesString everywhere instead of havingObject in certain places
• the class doesnot extendHashtable, it's a completely outdated class that shouldn't be used anymore
• thestore() methods donot write a timestamp at the top of the output
• thestore() methodswill write an empty line between any comments at the top of the output and the actual data

To build the project simply run:

./mvnw spotless:apply clean install