Configuration

Home > Core layer > Configuration

Overview

The configuration class offers a set of methods to load and store configuration values. A configuration value is identified by a name and a value. In its current version, ACS supports different value types (strings, booleans, numbers, class definitions, etc.).

When initializing a configuration object, you can either define its content directly through code or using XML files. Configuration objects can then be attached to an entity using the Entity.setConfig().

Initializing a configuration object

You can initialize an empty configuration object using the following code:

Config c = new Config();

You can initialize a configuration object from an XML file using the following code:

Config c = new Config("/path/to/my/config.xml");

Setting and getting configuration values

You can set and get configuration values using one of the setXXX and getXXX methods available in the configuration class.

For example:

Config c = new Config();

// setting values
c.setString("Name", "John");
c.setBoolean("Available", false);
c.setInt("Age", 20);

// getting values
String name = c.getString("Name");
boolean available = c.getBoolean("Available");
int age = c.getInt("Age");

Where to find configuration items related with a specific entity

Most of ACS' entities are well documented. Thus, you can find the configuration values which are used by a specific entity in its corresponding java doc.

Alternatively, you can also have a look at the FactoryUtils class which provides utility methods for generating entities and also describes the configuration values which are used in the process.

Finally, the sample configuration files provided with ACS also list and document configuration values.

Defining a configuration using XML files

The structure of a configuration is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<config>
</config>

You put configuration values between the <config> and </config> tags. The tag name will be mapped to the configuration name, and its value to the configuration value.

For example, if you want to set the same configuration values as in the previous section:

<?xml version="1.0" encoding="UTF-8"?>
<config>
	<name>John</name>
	<Available>false</Available>
	<Age>20</Age>
</config>

Nesting tags and configuration contexts

It is possible to nest XML tags. For example, consider the following file:

<?xml version="1.0" encoding="UTF-8"?>
<config>
	<client>
		<name>John</name>
		<Available>false</Available>
		<Age>20</Age>
	</client>
	<provider>
		<name>Jane</name>
		<Available>true</Available>
		<Age>32</Age>
	</provider>
</config>

In this case, there are two name configuration values that can be either accessed through the client or the provider context. See the following code:

Config config = new Config("/path/to/above/config.xml");

//
String clientName = config.getString("client.name");
String providerName = config.getString("provider.name");

//OR preferably:
String clientName = config.addContext("client").getString("name");
String providerName = config.addContext("provider").getString("name");

Including external files

Sometimes you may want to externalize some XML content for clarity and maintainability. In which case, you can use the <include> tag.

For example: <include>myOtherFile.xml</include> will include the given file.

Relative file name are resolved based on the directory of the current xml file (where the <include> is used).

Special / reserved tags

There are a few tags which have a special meaning. These are tags starting with add, edit and remove prefixes (case insensitive). For such tags, you can additionally specify an id attribute. We view there meaning in the following.

The add prefixed tags

The <addFoo> configuration tag adds a configuration named Foo in the current context.

This configuration does not replace existing configurations named Foo.

Instead, we keep a counter internally so that when you use multiple times the <AddFoo> tag, we actually create the following configuration values: Foo#0, Foo#1, ... etc.

If you want to create the configuration Foo, then use directly the tag <Foo>.

The edit prefixed tags

The <editFoo> tag changes current configuration context to Foo#n where n is defined the id attribute.

This method is useful to edit configurations inside contexts created using the reserved <AddFoo> tag.

The remove prefixed tags

The <removeFoo> configuration tag removes the configuration named Foo (or Foo#n where n is a number) in the current context. You must give its id using the id attribute.

If you use the wildcard (*) value for the id attribute, then all configurations in the current context whose name starts with Foo are removed.

The remove tag

The <remove> is similar to the previous tag, but it applies to all configurations in the current context independently from their name.