Basic Usage

The main important class in Apron is de.poiu.apron.PropertyFile. It provides methods to create a new instance by reading a .properties file from File or InputStream as well as methods for populating an instance programmatically.

The main difference to the usual java.util.Properties is that this class does not implement the java.util.Map interface and provides access to the content of the PropertyFile in two different ways:

  • as key-value pairs

  • as Entries

The key-value pairs are the actual interesting content of the .properties files and are the same as when read via java.util.Properties. However, since PropertyFile is able to retain all comments, blank lines and even the formatting of the file it stores all this information in objects of type Entry. There are two implementations of Entry:

  • BasicEntry
    A non-key-value pair like a comment or an empty line

  • PropertyEntry
    An actual key-value pair

The Entry objects store their content in escaped form. That means all whitespaces, linebreaks, escape characters, etc. are contained in exactly the same form as in the written .properties file.

The key-value pairs instead contain the content in unescaped form (as you would expect from java.util.Properties).

To minimize confusion the escaped values are stored as CharSequence whereas the unescaped values are stored as String.

A PropertyFile instance also allows writing its content back to disk. It provides 3 methods (each in two variants) for doing so:

  • overwrite
    Writes the contents of the PropertyFile to a new file or overwrite an existing file.

  • update
    Update an existing .properties file with the values in the written PropertyFile.

  • save
    Use either the above mentioned overwrite method if the given file does not exist or the update method if the file already exists.

The most interesting method is the update method, since this differentiates PropertyFile from java.util.Properties. It actually only updates the values of the key-value pairs without touching any other formatting. Blank lines, comments, whitespaces and even escaping and special formatting of the keys are not altered at all. Also the order of the key-value pairs remains the same.

The behaviour when writing a PropertyFile can be altered by providing it an optional ApronOptions object.

This is an example for a typical usage of PropertyFile as a replacement for java.util.Properties:

 1// Read the file "application.properties" into a PropertyFile
 2final PropertyFile propertyFile= PropertyFile.from(
 3  new File("application.properties"));
 4
 5// Read the value of the key "someKey"
 6final String someValue= propertyFile.get("someKey");
 7
 8// Set the value of "someKey" to a new value
 9propertyFile.set("someKey", "aNewValue");
10
11// Write the PropertyFile back to file by only updating the modified values
12propertyFile.update(new File("application.properties"));

This is an example for a more advanced usage of PropertyFile that allows accessing comment lines and explicitly formatted (escaped) entries:

 1// Read all Entries (that means BasicEntries as well as PropertyEntries)
 2final List<Entry> entries= propertyFile.getAllEntries();
 3
 4// Add a comment line to this PropertyFile
 5propertyFile.appendEntry(new BasicEntry("# A new key-value pair follows"));
 6
 7// Add a new key-value pair to this PropertyFile
 8// Be aware that by using appendEntry() it could be possible to insert
 9// duplicate keys into this PropertyFile. The behaviour is then undefined.
10// It is the responsibility of the user of PropertyFile to avoid this.
11// PropertyEntries contain their content in _escaped_ form. Therefore the
12// Backslashes and newline character are not really part of the key and value
13propertyFile.appendEntry(new PropertyEntry("a new \\\nkey", "a new \\\nvalue"));
14
15// key-value pairs are _unescaped_. Therefore the following method call
16// will return the string "a new value"
17final String myNewValue= propertyFile.get("a new key");
18
19// Specify an ApronOptions object that writes with ISO-8859-1 encoding
20// instead of the default UTF-8.
21final ApronOptions apronOptions= ApronOptions.create()
22  .with(java.nio.charset.StandardCharsets.ISO_8859_1);
23
24// Write the PropertyFile back to file by only updating the modified values
25propertyFile.update(new File("application.properties"), apronOptions);

See the Javadoc API for more details.