Using properties files to load Extension settings

Often times server-side code requires a number of configuration parameters that can be easily tweaked without recompiling and re-deploying the Extension. In this article we will show a useful and little known feature of SFS2X’s Extensions.

Did you know you can user properties files to store your Extension’s runtime configuration and have it loaded auto-magically for you? If you have carefully read the documentation you probably already know this , otherwise keep reading…

» What is a “properties” file

In the Java SDK “properties” files are simple text files containing key value pairs such as these:

language=eng
timeout=100
isActive=true

where the string on the left side of the equal sign represents the key and the one on the right represents the corresponding value.

NOTE: there shouldn’t be spaces before and after the equal sign.

» Extension’s default configuration

Every SmartFoxServer 2X  Extension expects an optional config.properties file located in the same deployment folder. If such file exists it will be auto loaded at init() time and all of its properties exposed via the getConfigProperties() method, which returns a java.util.Properties object.

Using the previous example properties file here’s how we can access its data at runtime:

@Override
public void init()
{
	Properties props = getConfigProperties();

	String language = props.getProperty("language");
	int timeout = Integer.parseInt(props.getProperty("timeout"));
	boolean isActive = Boolean.parseBoolean(props.getProperty("isActive"));
}

Properties objects treat every value as a String so we need to convert the int and boolean data from the file accordingly. We can also provide a default value for each key if we are not sure that an item will be present in config file. For instance:

Properties props = getConfigProperties();

String language = props.getProperty("language", "eng");

In this case the “eng” value will be the default when the “language” key is not present in config.properties.

» Using multiple or custom Properties files.

You may also use multiple properties files to store other data from your Extension in the local file system. The Properties class exposes useful methods to save and load data to local disk both in text and xml format.

Here’s an example of custom saving and loading a Properties instance (as text file):

private Properties loadProps(String fileName)
{
	Properties props = new Properties();

	try
    {
		props.load(new FileInputStream(fileName));
    }
    catch (IOException e)
    {
    	// Log error
    }

	return props;
}

private void saveProps(Properties props, String fileName)
{
	try
	{
		props.store(new FileOutputStream(fileName), "optional comments");
	}
	catch (IOException e)
	{
		// Log error
	}
}

The code should be self-explanatory. There is one minor note for the store(…) method, which takes a 2nd parameter where you can specify comments that will be prepended to the file.

NOTE: if you’re using relative paths for loading/storing files keep in mind that every Extensions sees the SFS2X/ folder as their root. If you are storing your files side by side with your Extension the relative path can be built like this:

extensions/<your-ext-name>/<filename>.properties

» Conclusion

Storing your Extension’s settings in the default config.properties file can be very handy as you can reconfigure your code while it runs, without the need of recompiling and re-deploying.

A simple reload of the Extension will trigger the update of the settings or, if you want to avoid any reloads at all, you can manage your own custom .properties files and reload them with specific Extension commands.