Configuration

The Weave configuration is stored in an XML file, config.xml, and it describes the items that Weave should use to do things like connecting to databases, laying out a Table of Contents or defining access control.

The basic configuration file contains a standard XML header, a root config tag that defines the namespaces for the items that will be defined within the config file, and the tags within the root config tag that define all of the configuration items that setup the Weave server for operation.

The following example shows the bare minimum require of the config.xml file, including the xml header, the root config tag and the setting of the default namespace.

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

<config xmlns="urn:com.cohga.server.config#1.0">       
<!-- configuration items defined here -->
</config>

The configuration of the Weave server involves adding configuration items to this basic config file until all the parts that are required to build a running systems are in place.
Before we can start adding configuration items to the config.xml file we need to familiarize ourselves with namespaces, which is used to join configuration items to the server components that are responsible for implementing them.

Namespaces

The Weave configuration file uses namespaces to provide flexibility in the configuration. Rather than having a single monolithic pre-defined configuration format the Weave server uses plugins to process different parts of the configuration file and the namespaces are used to indicate to the server which plugins should be used to process which parts. In this way new components can be added to the system and can include their own configuration options in config.xml without having to make any changes to the core Weave infrastructure.

The namespaces for internal Weave plugins follow the format urn:pluginid#version, but there are situations where other namespaces can used in the config file for example when referencing XMLSchema elements.

The configuration file outlined above is of little use in its current form as it doesn't define any configuration items for the server to use so let's expand the configuration to include an example configuration item.

The first thing that we need to do is add a namespace for the plugin that will be processing our new configuration item. For our example we will use a dummy plugin with the id com.cohga.weave.example. We will be using version 1.0 so the namespace we will need to add is urn:com.cohga.weave.example#1.0

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

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:example="urn:com.cohga.weave.example#1.0">
</config>

What we have done here is to create a namespace place holder called example, that is used later in the configuration file to reference the actual namespace, urn:com.cohga.weave.example#1.0.

Adding the namespace is not enough to create a new configuration item. It simply tells the configuration file reader that anything referencing the namespace should be handled by the particular plugin, but more on that later.

For now we'll use the namespace to create the new configuration item. Normally this is where you would consult the Configuration Reference to find out the structure/content of the item, since each plugin has its own requirements for what needs to be included within it.

For this example we will just make something up and add the item.

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

<config xmlns="urn:com.cohga.server.config#1.0" xmlns:example="urn:com.cohga.weave.example#1.0">

  <example:greeting id="greeting.english">
    <text>Hello World</text>
  </example:greeting>

</config>

Here we've created an example configuration item.

Now we have a working configuration file that will create an example item when the server starts. But what is actually happening here?

Parsing

The important things to note in our example are the use of the namespace to enclose the configuration of this particular item, the setting of the configuration item type (in this example it's greeting), the unique identifier given to the item greeting.english, and the actual content of the configuration item.

The id, in this example greeting.english, is used to uniquely identify individual configuration items, and should be unique for each combination of namespace and type. That is you can have the same id for an example:greeting configuration item, an example:message configuration item and a test:greeting configuration item, but you can not have the same id for two example:greeting configuration items.

The item needs to be uniquely identified for two reasons, the first one is that if the content of the configuration item is changed the configuration file reader can notify the system that this particular item has been changed, the other reason is so that the item can be referenced by other configuration items.

Not all items actually require an id however, if there will only ever be one instance of the particular object that the configuration item is supposed to represent, and the item never needs to be referenced by other configuration items, then it may be possible to not use the id. An example of this would be the configuration of a mail server. Since there is only a single mail server required for Weave to send email and no other configuration item will be required to reference that particular configuration, then only one configuration item is required.

When the configuration file reader parses the config.xml file it looks at all of the top level items (i.e. those immediately below the root config tag), and determines the namespace for those items. For each of these items it locates a plugin registered against that namespace and passed the entire contents of the configuration item to the plugin, along with the version number used in the namespace definition and the configuration item type.

It is up to the plugin to examine the item passed to it to extract the information that it requires. In the above example, the plugin will extract the id, greeting.english, and the text, "Hello World", and do whatever is appropriate for the plugin.

Other configuration items can refer to this particular greeting, using its id, and the system will link the two items at runtime.

In this manner, adding required namspaces and configuration items, the configuration file is built up to compose a working Weave server using only those components that the server requires.

The Configuration Reference details what core components are available for you to use as part of your configuration and what the appropriate contents should be for each.

Processing Instructions

When processing the configuration file, Weave provides a couple of processing instructions that may help to make your life a little easier. They are include and set. These instructions provide a means to alter the configuration items before they are processed.

The Processing Instructions page outlines the use of these instructions.

Null Values

Occasionally there are times when you need to un-set a value, you do this using a null.

The Null Values page outlines how to include 'null' in your configuration and why you would do this.