Props
Jodd Props is Java properties on steroids: containing all that is missing in JDK: UTF-8 support, macros, sections, profiles, fully configurable... and more! Properties are stored in one or more *.props files, but its architecture is open for any type of source.
Jodd Props is compatible with Java properties.
The purpose of Jodd Props is not to provide the ultimate configuration solution, but to replace Java properties with a similar but better alternative. If you are already using Java properties in your application, or just want a familiar and friendly configuration, consider switching to Jodd Props.
Jodd Props configuration is stored in text file(s), with default extension .props. Still, Props is compatible with Java properties and knows to load *.properties as well. Here is screenshot of a props file:
By default, props files are UTF-8 encoded. However, Jodd Props will always load Java's properties using ISO 8859-1.
Leading and trailing spaces will be trimmed from section names and property names. Leading and/or trailing spaces may be optionally trimmed from property values.
Either equal sign (=) or colon (:) are used to assign property values.
Use += to append values (separated by comma) of properties with the same name.
Comments begin with either a semicolon (;), or a sharp sign (#) and extend to the end of a line. It doesn't have to be the first character of a line.
The backslash (\) escapes the next character (e.g., \# is a literal #, \\ is a literal \).
If the last character of a line is backslash (\), the value is continued on the next line with a new line character included.
\\uXXXX is encoded as a character. Also \t, \r and \f are encoded as characters as well.
Use triple-quote to define multi-line values in a convenient way.
Using Jodd Props is very easy. In a nutshell, properties are managed by Props class.
Props p = new Props();p.load(new File("example.props"));...String story = p.getValue("story");
Properties can be loaded by Props in many different ways: from a File, InputStream, String or Properties. Once loaded, props are ready for usage. Values can be looked up using the getValue() method. This method always returns a String value.
In Props, a section simply defines a key's prefix for the following set of keys, until the section or file ends.
Section name is enclosed between [ and ]. Properties following a section definition belong to that section. Section name is added as a prefix to section properties. Section ends with empty section definition [] or with a new section start or end of the file.
The following example:
[users.data]weight = 49.5height = 87.7age = 63[]comment=this is base property
is identical to:
users.data.weight = 49.5users.data.height = 87.7users.data.age = 63comment=this is base property
Sections can shorten the file and make it more readable.
Often an application works in different environments and, therefore, requires a different set of properties. For example, the development mode and deployment mode of an application. One way how to organize properties is to define different profiles where the same key name takes different values.
Props supports property profiles. Profiles are defined within the key name: profile name is enclosed between < and >. One key may contain one or more profile definitions. Profile definition can exist anywhere in the key name, even in the middle of the word; however, it is a good practice to put them at the end.
Properties without a profile are base properties. If lookup for a property of some profile fails, Props will then examine the base properties.
Profiles can be considered as 'different views' or 'snapshots' of the same property set.
Example:
db.port=3086​db.url<develop>=localhostdb.username<develop>=root​db.url<deploy>=192.168.1.101db.username<deploy>=app2499
In this example 3 keys are defined; two keys have different values in two profiles (develop and deploy) and have no base value.
Since sections are just a prefix definition and since profile can be located anywhere in the key name, the section name can define profile definition as well! The above example can be written as:
db.port=3086​[db<develop>]url=localhostusername=root​[db<deploy>]url=192.168.1.101username=app2499
When looking up for a value, it is possible to specify which profiles are active:
String url = props.getValue("db.url", "develop");String user = props.getValue("db.username", "develop");
More than one profile can be specified at a time. The order of specified profiles is important! When one key is defined in more than one active profile, the FIRST value (of first matched profile) is returned. {: .attn}
It is also possible to lookup only for base properties (ignoring the profiles) - using getBaseValue() method. Base properties are those that don't belong to any profile.
Usually, only one set of profiles is active during the application's lifetime. Instead of passing active profiles to getValues() methods each and every time, Props allows defining so-called active profiles externally, in the same props files used for loading properties.
The active profiles are the default when looking for a property using method getValue(String).
Active profiles can be defined in the props files - this way the configuration set can be changed (i.e. active profiles can be modified) without the need to recompile the code. Active profiles are defined under the special base key named @profiles. Example:
key1=hellokey1<one>=Hi!​@profiles=one
and the following Java code:
String value = props.getValue("key1");
would return the value Hi!, since the active profile is one.
Active profiles can be set from Java, too, using the method: setActiveProfiles().
There are situations where two or more profiles share the most of the configuration and only a few properties are different (or: specific) for one profile (i.e. configuration). To avoid repeating of all properties for each profile, it is possible to define properties assigned to inner profiles only for those differences. Props will first lookup keys in inner profiles, then go up to the base level. Example:
key1<one>=Hi!key2<one>=.......key100<one>=...​key1<one.two>=Hola!
This example defines two profiles. The first one is named one and contains 100 properties. The second profile is an inner property named one.two. It contains only 1 property (key1) - but all properties from its upper profile are available! What happens when Java code calls the following: props.getValue("key1", "one.two")? Props will:
lookup for property in inner profile
one.twoif a value is not found, Props will check upper profile:
oneif a value is not found and there are no more upper profiles, Props will check base properties.
There can be any levels of inner profiles.
The biggest Props strength are macros. Macro is a reference to a value of some other key. Macros are enclosed between ${ and }. Here is a simple example:
key1=Something ${foo}...foo=nice
Value of key1 is Something nice. Macros can refer to any existing property key, no matter where it is defined.
Nested macros are also supported. Example:
key1=!!${key${key3}}!!key3=2key2=foo
Value of key1 is !!foo!!.
Macros are always resolved using the currently active or provided profile. The value of macro may change if current profile is changed.
This behavior is controlled with flag: useActiveProfilesWhenResolvingMacros. Here is an example:
root=/approot<foo>=/foodata.path=${root}/data
What is the value of data.path when foo profile is set as active? Since foo is active, root value becomes /foo, therefore the data.path is going to be set to /foo/data value.
If we turn off profiles (and use only base propertes), the data.path value is going to be /app/data.
It is also possible to explicitly set macro's profile:
root=/approot<foo>=/foodata.path=${root<foo>}/data
In this example, root macro will always use the foo profile regardless of the currently selected profiles. So data.path value would be always be: /foo/data.
When enabled, multilines values may be defined with triple-quotes. Everything between is considered as a value. Example:
email.body='''Hello $n,​welcome!'''
Note that multiline values are NOT trimmed! Therefore, the value from the example will consist of 5 rows.
Props keeps your keys in order! It is possible to iterate all Props keys in the same order as they are listed in the props file(s). So instead doing this:
foo.1=value1foo.2=value2...
you can simply iterate props using:
Props props = ....Iterator<PropsEntry> it = p.iterator();
The order of iteration is the same as the order of props definitions!
But there is more - it is possible to furthermore tune the iterator, by adding a filter for profiles to look and/or sections to iterate. So you can write something like this:
Iterator<PropsEntry> it = p.entries().section("one.two").profile("prof1", "prof2").iterator();
to iterate only props in given section and for given profiles.
Due to profiles usage, one key may be defined on many places in props file. For example, you can specify value for two profiles. In this case, it is not clear what is the 'correct' order of the keys: should it be the first appearance of the key, or the place where it gets its value? Either way, you can control this behavior using skipDuplicatesByValue() and skipDuplicatesByPosition() during iterator building.
Imagine you have certain number of properties that is, by default, the same for some number of different categories. For example:
com.jodd.action1=value1com.jodd.action2=value2...org.jodd.action1=value1org.jodd.action2=value2...net.jodd.... # etc
Props allows you to use copy operator: <= to minimize duplication of the props. Above props can be written as:
[actions]action1=value1action2=value2...​[]org.jodd <= actions​[com]jodd <= actions​[net.jodd]<= actions
This example shows three different ways how to use copy operator, without a section, with partial section name or with full section name. All three ways are identical and it's up to you which one you gonna use.
Remember that copied values are set as macros, so all above copied properties are identical to:
org.jodd.action1=${actions.action1}com.jodd.action1=${actions.action1}....
All rules for resolving macros applies.
