What are property filters?

Filters are a method to give several values to a property and choose one of them based on the value of one or more selectors. They have been found particularly useful in environments which have heavy personalization requirements, although thay can be very handy in a lot of other situations

As an example will take a property called skin which defines the default skin of a user in an educative portal. The users are categorized in types differentiating teachers from students from others. The students are further subdivided depending on their grade level (primary, secondary, etc). We want to let the person configuring the portal set a different default skin depending on the type of user. To do this we retrieve the property value using the user type and subtype as selectors: 

getProperties().getString("skin", Filter.by(userType, userSubtype));

In the properties file the skin property may be given different values depending of the values of the user type and subtype. For example: 

skin[teacher]=blue
skin[student][secundary]=green
skin[student]=yellow
skin=grey

With this configuration the default skin is grey and it will be applied to users which are not teachers neither students. For students the default skin is yellow unless it is of subtype secundary in which case the default skin will be green. It is important to know that it is optional and up to the person writting the configuration to use selector values or not. He/she can just give a simple value to the property. Using filters from code when retrieving the property value just offers the possibility to the configurator.

EasyConf supports an unlimited number of selectors. They can be optionally used in any of the supported property types with or without a defautl value. Check the Javadoc of the Filter class for more information

Variable based filters

New on version 0.9

While the above functionality is enough for most cases, sometimes it is desired to have value of the property which depends on a value only known by the running application. For example a servlet may wish to configure a URL but make it dependent on the current host name and port. EasyConf supports this functionality though a special type of filter. To implement the previous example the properties file should have: 

external-app.url=http://${host}:${port}/external-app
When this property is read the application can provide the values of the host and port variables: 
Map hostAndPort = new HashMap();
hostAndPort.put("host", host);
hostAndPort.put("port", port);
getProperties().getString("external-app.url", Filter.usingVariables(hostAndPort));
The variable values can be provided in any bean that implements the java.util.Map interface. Besides there are conveniency methods for cases with three or less variables. Using them the previous example could be rewriten as: 
getProperties().getString("external-app.url", 
								  Filter.usingVariables("host", host, "port", port));
If a property's value has a variable and its value is not provided. The variable string (${variableName}) will be returned instead. On the other hand, the name of a variable can be the same as the key of another property. In that case the value of the property will be used if the variable is not given a value programatically using variable based filters

Filters based on selectors and filters based on variables can be combined. An example would be: 

getProperties().getString("external-app.url", 
								  Filter.by(appName).setVariables("host", host, "port", port));
Check the Javadocs for more information.