Usage

The usage of Configuration Utils is defined by the IConfigurations interface.

You will see by examining this API that you have methods for the three basic needs for managing configurations:

  1. Read a configuration (overloaded method readConfiguration)
  2. Write a configuration (overloaded method writeConfiguration), that performs the writing to the repository of new configurations or updates the existing ones
  3. Remove a configuration (overloaded method readConfiguration), deletes all entries for the specified configuration/section identifier

These are all that is needed to manage the Configuration repository.

Initialization

The current implementation, ConfigurationsPreferencesImpl, needs no initialization. The underlying API takes care of this for us. New implementation to come are advised to make all needed initialization in their constructors.

This means that besides instanciating the implementation class there is no initialization needed.

 1  IConfigurations configAPI = new ConfigurationsPreferencesImpl();

How to use it

As we have stated before, the reading and writing methods are overloaded. They provide several use cases:

As you could read on the notes above, two of these cases have dedicated sections on the User Guide, so we'll focus on the simplest of cases, the Properties objects. See more on the other two on the corresponding sections.

Properties class objects

The Properties as we may know is a class that provides the managment of key/value pairs. Check out it's API in SUNs JavaDocs.

Properties has been used extensivly by the Java community for configuration files managment, by using it's convenient load and store methods to read and write from a file/stream. This is the reason that we decided to implement this easy, and most probably backwards compatible, usage.

We can then read and write Properties objects.

What are the advantages that Configuration Utils provides over direct usage of the Properties class?

One of the main advantages is having to divide into several Properties files our configurations. This because there is no support for sectioning or any other organizational structure in Properties files.

Another common issue is where to write the files. The available directories vary with each environment our applications runs, and so, the available resources are not constant. Much boilerplate code is written specifically for this concern alone.

Configuration Utils takes care of all this for us, provides the integration of these Properties objects with the underlying Java Persistence API and thus shielding of these concerns.

Examples of usage

Let's now see some basic examples:

 1  IConfigurations configAPI = new ConfigurationsPreferencesImpl();
 2
 3  Properties props1 = new Properties();
 4  props1.put("key1", "Some value #1");
 5  props1.put("key2", "Some value #2");
 6
 7  configAPI.writeConfiguration("ConfigAPI Example","PropertiesSection", props1);
 8
 9  Properties props2 = new Properties();
10  props2.put("key1", "Some value #1 - CHANGED");
11  props2.put("key3", "Some value #3");
12
13  configAPI.writeConfiguration("ConfigAPI Example","PropertiesSection", props2);

In the previous code we can see that it's very easy to use this API. The properties are saved in the Configuration Utils repository without questions asked.

We have compiled in this example a few cases so we can see how the API performs on some situations.

  • Will each write operation overwrite the previous data?: No, it will not. Writes as cumulative. Previous data gets updated.
  • In a write of an existing section, how will missing keys be processes?: Missing keys are ignored. All included keys in the Properties object passed are saved to the repository, overwriting old values if present, all other keys in the repository will remain untouched.

Let's now see a read example, in sync with the previous example:

 1  IConfigurations configAPI = new ConfigurationsPreferencesImpl();
 2
 3  Properties props = new Properties();
 7  props = configAPI.readConfiguration("ConfigAPI Example","PropertiesSection");
 8
 9  for (Object key : props.keys())
10      System.out.println(key + ": " + props.get(key));
11
12  configAPI.removeConfiguration("ConfigAPI Example","PropertiesSection");

This will generate the following output:

key1: Some value #1 - CHANGED
key2: Some value #2
key3: Some value #3

Here we can confirm that the values are updated over consecutive calls to the write method, and that we can make partial inserts/updates to existing configuration sections, preserving the previous data unchanged.

In the end of the previous example, all keys in this section are removed. Simple as that.

There is no more to see in using Configuration Utils with Properties objects. All is simple, since the Properties are simple by nature and much is done internally by the Configuration Utils API.